For most Node.js developers choosing between npm, pnpm and Yarn, the right pick is pnpm or npm, and Yarn fits only narrower cases. The choice matters because it sticks. Once a lockfile exists (the file that records the exact version of every installed package), switching means resolving the whole dependency tree again, and some versions may shift.
Pick pnpm if you run a monorepo, meaning several apps or packages in one repository linked through workspaces, or if CI (continuous integration) install time matters. pnpm keeps a content-addressable store, a shared folder where each package version is saved once and linked into every project. Stay on npm if you want the tool that ships with Node and works with every Docker image and build tool. Choose Yarn Berry (version 2 and later) only if your team is ready to adopt Plug’n’Play, its mode that skips node_modules/ and does not work with some tools. If you still run Yarn Classic (version 1), plan a move off it, since it is no longer maintained.
How to verify
See what your repo currently uses and the disk impact:
ls *.lock* package-lock.json yarn.lock pnpm-lock.yaml 2>/dev/null
du -sh node_modules/
node_modules/.bin/.package-lock.json 2>/dev/null | head -3
which npm pnpm yarn
npm config get cache
pnpm store status # pnpm only — shows shared store usage
If you find both package-lock.json and yarn.lock, you have two competing sources of truth and a divergent install across developers. Pick one and delete the other.
What’s happening
npm writes a flat-ish node_modules/ (hoisted) and tracks state in package-lock.json. Resolution is greedy: every package version goes somewhere in the tree, hoisted to the top where possible. It’s the default, works everywhere, and the lockfile is well-understood. Install speed has improved dramatically in npm 9-10 but is usually still slower than the competitors on cold installs.
pnpm writes a virtual node_modules/ that’s a directory of symlinks pointing into ~/.local/share/pnpm/store/. Every unique (package, version, content) tuple is downloaded once and reused across every project on the machine. Disk savings are substantial — a 1 GiB project might use 100 MiB of net disk. Resolution is strict by default: a package can only import what it declares in its package.json, catching phantom dependencies that npm’s flat layout would silently accept.
Yarn Berry (v2+) supports both Plug’n’Play (.pnp.cjs — no node_modules/ at all, resolution at runtime via a generated lookup) and nodeLinker: node-modules (npm-like). PnP is faster and cleaner but breaks some tools that walk node_modules/. Berry is the most opinionated and rewards teams willing to learn it; Yarn Classic (v1) is unmaintained and should be migrated off.
The decision
| Criterion | npm | pnpm | Yarn Berry |
|---|---|---|---|
| Install speed (cold) | Baseline | 1.5-3x | 1.2-2x |
| Install speed (warm) | Baseline | 3-5x | 2-3x |
| Disk usage | High | Low (shared store) | Low with PnP |
| Phantom dependency catch | No | Yes | Yes (PnP) |
| Workspaces / monorepo support | Workspaces (good) | Workspaces (excellent) | Workspaces (excellent) |
| Lockfile compatibility | Universal | pnpm-only | Yarn-only |
| Native module support | Universal | Universal | PnP breaks some |
| CI cache friendliness | Moderate | Good | Good |
| Bundled with Node | Yes | No | No |
| Adoption in ecosystem | Largest | Growing fast | Stable |
| Operational tooling for ops/Docker | Universal | Excellent | Newer |
Pick pnpm when:
- You run a monorepo or have many projects on the same machine (disk store is shared)
- You want phantom-dep detection caught early
- CI install time matters and you can configure pnpm-aware caching
Pick npm when:
- You want the lowest-friction default that ships with Node
- The team isn’t ready to standardize on a non-default tool
- Docker base images and tooling assume npm
Pick Yarn Berry when:
- The team is willing to invest in Plug’n’Play and its quirks
- You have a polyglot monorepo where Yarn’s plugins help
Migrate off Yarn Classic regardless — it’s unmaintained and security advisories now flow through the Berry advisory database.
The procedure (migrating npm to pnpm)
-
Install pnpm via Corepack (preferred — version is pinned in
package.json):corepack enable corepack prepare pnpm@latest --activate -
Run the migration in the project. pnpm will read
package-lock.jsononce and convert:pnpm import # generates pnpm-lock.yaml from package-lock.json rm package-lock.json node_modules -rf pnpm install -
Catch and fix phantom dependencies — packages your code imports that aren’t in
package.json. pnpm’s strict layout exposes them:pnpm test # if anything fails with "Cannot find module 'X'", add X to package.json pnpm add X -
Update CI to use pnpm. The GitHub Actions setup:
- uses: pnpm/action-setup@v4 with: { version: 9, run_install: false } - uses: actions/setup-node@v4 with: { node-version: '20', cache: 'pnpm' } - run: pnpm install --frozen-lockfile -
Update Dockerfile. For Node base images that don’t include pnpm, install via Corepack:
FROM node:20-alpine RUN corepack enable && corepack prepare pnpm@latest --activate WORKDIR /app COPY pnpm-lock.yaml package.json ./ RUN pnpm install --frozen-lockfile --prod COPY . . CMD ["pnpm", "start"] -
For workspaces, declare them in
pnpm-workspace.yaml:packages: - 'apps/*' - 'packages/*'
Common pitfalls
- Committing two lockfiles.
package-lock.json+pnpm-lock.yamlin the same repo confuses tooling and produces non-deterministic installs across developers. Pick one. - pnpm symlinks confuse some tools that walk the filesystem (some legacy bundlers, some IDE plugins). Configure with
node-linker=hoistedin.npmrcif you hit a real incompatibility, but you lose the disk savings. - Yarn Berry’s
.yarn/cacheshould usually NOT be committed despite Berry’s “zero-installs” feature — the cache balloons the repo to gigabytes. Commityarn.lockand.yarnrc.yml, gitignore.yarn/cacheand.pnp.*. - Corepack version pinning lives in
package.json“packageManager”. CI must runcorepack enableor it will silently use the system-installed version, defeating the pin. npm ci/pnpm install --frozen-lockfile/yarn install --immutableall do the same thing — install exactly the lockfile, fail if drift. Use these in CI, not the regularinstall, or your lockfile silently updates and Snyk / npm audit results drift.
For the supply-chain side of the same conversation, see npm audit and Snyk and supply-chain security with LavaMoat. In the engagements Stack Harbor runs, pnpm is the default for new services that have multiple workspaces, npm is the default for everything else; the lockfile is committed, Corepack pins the version, and the install command in CI is the immutable variant — these are part of managed operations, not optional housekeeping.