As projects grow, the choice of package manager starts to matter more. npm is the default package manager for Node.js, but once performance, disk usage, and install speed become important, more teams start moving to pnpm, especially on larger projects.
If you are considering switching from npm to pnpm, this guide covers the practical steps and the most common issues you may hit.
1. Install pnpm
If you currently use npm, the first step is to make sure pnpm is available. There are a couple of common ways to install it.
Install with Homebrew
On macOS:
brew install pnpm
If you already have it installed and just want the latest version:
brew upgrade pnpm
Install with npm
If you do not use Homebrew, install it globally through npm:
npm install -g pnpm
2. Switch an existing project from npm to pnpm
After moving to pnpm, the old node_modules directory and package-lock.json file should be replaced by pnpm's own dependency model.
Step 1: remove node_modules and package-lock.json
rm -rf node_modules package-lock.json
Step 2: reinstall everything with pnpm
pnpm install
This creates a new pnpm-lock.yaml file and rebuilds your dependencies using pnpm's structure.
3. Configure pnpm
If you previously had dependency resolution problems under npm, pnpm offers a config called shamefully-hoist, which can make dependency layout behave more like npm by hoisting packages to the top-level node_modules.
That is useful when some packages incorrectly assume that dependencies live directly in the root node_modules.
Enable it like this:
pnpm config set shamefully-hoist true
This can solve compatibility problems, though you should only turn it on if you actually need it.
4. Running scripts with pnpm
Your package.json scripts do not need to change. pnpm is compatible with npm script definitions, so a scripts section like this still works:
{
"scripts": {
"dev": "vite",
"build": "vite build",
"lint": "eslint .",
"preview": "vite preview"
}
}
The only change is the command you type:
- start the dev server:
pnpm run dev - build the project:
pnpm run build - run ESLint:
pnpm run lint - preview the build:
pnpm run preview
5. Cleanup and troubleshooting
If installs hang or behave strangely, cache or disk space issues are often involved. These commands help.
Clean the pnpm store
pnpm store prune
Check disk space
pnpm uses a global store and creates dependency directories on disk. If storage is tight, installs can fail or get stuck. Check available space with:
df -h
6. Common migration problems
Problem 1: install hangs
Possible causes include cache problems, low disk space, or network issues.
Try:
pnpm store prune
rm -rf node_modules pnpm-lock.yaml
pnpm install
Problem 2: dependencies are not resolved correctly
If some packages cannot find what they need, confirm whether shamefully-hoist should be enabled. If necessary, delete node_modules and reinstall.
Problem 3: permission errors
On macOS or Linux, install commands can fail because of permission problems. Make sure you have the required permissions, or use a safer environment setup rather than blindly adding sudo everywhere.
Summary
Moving from npm to pnpm is usually straightforward, especially because pnpm keeps compatibility with standard npm scripts.
A clean migration usually looks like this:
- install pnpm
- remove
node_modulesandpackage-lock.json - run
pnpm install - enable
shamefully-hoistonly if needed - run your scripts and verify the project works
Once you switch, you usually get faster installs, better cache reuse, and lower disk usage.
If anything goes wrong, the fixes are usually simple: clean the store, reinstall, and check whether your project depends on npm-style hoisting behavior.