Skip to content

npm vs pnpm vs Yarn — choosing a Node.js package manager

Compare npm vs pnpm vs Yarn and pick the Node.js package manager that fits your project. pnpm suits monorepos and busy CI pipelines, npm is the lowest-friction default, and Yarn Berry fits teams ready to adopt Plug'n'Play.

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

CriterionnpmpnpmYarn Berry
Install speed (cold)Baseline1.5-3x1.2-2x
Install speed (warm)Baseline3-5x2-3x
Disk usageHighLow (shared store)Low with PnP
Phantom dependency catchNoYesYes (PnP)
Workspaces / monorepo supportWorkspaces (good)Workspaces (excellent)Workspaces (excellent)
Lockfile compatibilityUniversalpnpm-onlyYarn-only
Native module supportUniversalUniversalPnP breaks some
CI cache friendlinessModerateGoodGood
Bundled with NodeYesNoNo
Adoption in ecosystemLargestGrowing fastStable
Operational tooling for ops/DockerUniversalExcellentNewer

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)

  1. Install pnpm via Corepack (preferred — version is pinned in package.json):

    corepack enable
    corepack prepare pnpm@latest --activate
  2. Run the migration in the project. pnpm will read package-lock.json once and convert:

    pnpm import      # generates pnpm-lock.yaml from package-lock.json
    rm package-lock.json node_modules -rf
    pnpm install
  3. 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
  4. 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
  5. 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"]
  6. For workspaces, declare them in pnpm-workspace.yaml:

    packages:
      - 'apps/*'
      - 'packages/*'

Common pitfalls

  • Committing two lockfiles. package-lock.json + pnpm-lock.yaml in 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=hoisted in .npmrc if you hit a real incompatibility, but you lose the disk savings.
  • Yarn Berry’s .yarn/cache should usually NOT be committed despite Berry’s “zero-installs” feature — the cache balloons the repo to gigabytes. Commit yarn.lock and .yarnrc.yml, gitignore .yarn/cache and .pnp.*.
  • Corepack version pinning lives in package.json “packageManager”. CI must run corepack enable or it will silently use the system-installed version, defeating the pin.
  • npm ci / pnpm install --frozen-lockfile / yarn install --immutable all do the same thing — install exactly the lockfile, fail if drift. Use these in CI, not the regular install, 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.