npm vs Yarn vs pnpm: Which Package Manager to Use
The three Node package managers differ in speed, disk usage and strictness. Learn the trade-offs and how to choose for a project.
By Velloreth
What they have in common
All three read package.json, resolve the dependency tree, download from the npm registry, and write a lockfile. The differences are in how they store the packages, how strict the layout is, and how fast a cold install is.
The choice matters less than consistency. A repository with one lockfile and one manager is reproducible. A repository with two lockfiles is a source of confusion.
npm
npm ships with Node, which is its main advantage: there is nothing to install.
npm install
npm ci
npm run build
npm ci is the CI command. It installs exactly what the lockfile specifies, does not modify the lockfile, and removes node_modules first.
npm install may update the lockfile. It resolves the ranges in package.json, which can produce a different tree than the lockfile. It is the right command for adding a dependency and the wrong one for a build.
npm hoists packages into a flat node_modules, which means a package can import a dependency it did not declare and still work. This is the phantom dependency problem.
Workspaces are supported, which makes npm usable for a monorepo.
Yarn
Yarn added a lockfile and workspaces before npm had them, which is why it was widely adopted. npm has since caught up, so the original advantage is smaller.
Yarn Classic (1.x) is the version most projects still use. It is compatible with npm’s node_modules layout.
Yarn Berry (2.x and later) is a rewrite. It adds Plug’n’Play, which removes node_modules and resolves packages from a zip archive, and it adds a stricter resolution model.
Plug’n’Play is a real change. It is faster and it uses less disk, and it breaks a tool that assumes node_modules exists. It is opt-in, and a project that needs a tool with that assumption should not use it.
yarn install
yarn add lodash
yarn dlx create-react-app my-app
yarn dlx runs a package without installing it, which is the equivalent of npx.
pnpm
pnpm uses a content-addressable store and hard links. A package is stored once on the machine, and every project links to it, which saves a large amount of disk on a machine with several projects.
pnpm install
pnpm add lodash
pnpm dlx create-react-app my-app
The layout is strict. node_modules contains symlinks to the store, and a package can only import what it declared. A phantom dependency fails immediately, which surfaces a real bug that npm and Yarn hide.
The strictness is the main reason to choose pnpm. A package that works under pnpm is a package whose dependencies are correct, and it will not break when the hoisting changes.
It is usually the fastest for a cold install on a large project, because the hard link is cheaper than a copy.
The store is shared, so a second project installs almost instantly for the packages it has in common.
The comparison
| Concern | npm | Yarn | pnpm |
|---|---|---|---|
| Ships with Node | Yes | No | No |
| Disk usage | High | High | Low |
| Cold install | Slow | Medium | Fast |
| Strictness | Hoisted | Hoisted | Strict |
| Workspaces | Yes | Yes | Yes |
| Lockfile | package-lock.json | yarn.lock | pnpm-lock.yaml |
| Phantom deps | Hidden | Hidden | Surfaced |
Choosing
A new project with no constraint: pnpm, for the disk usage and the strictness.
A project that must work with the default tooling: npm, because it ships with Node and every tool supports it.
A project already on Yarn: stay on Yarn, unless there is a reason to migrate. A migration is a real cost for a small benefit.
A monorepo: pnpm or Yarn workspaces. The disk saving and the strictness matter more at that scale.
A library that others will install: test with all three, because a consumer may use any of them.
The lockfile rules
Commit exactly one lockfile. A repository with package-lock.json and yarn.lock has two sources of truth, and the install depends on which command was run.
Do not edit a lockfile by hand. It is generated, and a manual edit is not reflected in the resolution.
Use the frozen install in CI. npm ci, yarn install --immutable, or pnpm install --frozen-lockfile. Each fails if the lockfile does not match package.json, which catches a dependency that was added without committing the lockfile.
Add the lockfile to the review. A lockfile diff shows a transitive dependency that changed, which is often the cause of a build that breaks without a source change.
Migrating
# From npm to pnpm
rm -rf node_modules package-lock.json
pnpm install
git add pnpm-lock.yaml
git rm package-lock.json
Delete node_modules first. A leftover tree from the old manager confuses the new one.
Update the CI and the docs. A README that says npm install and a CI that runs pnpm install is a source of confusion.
Add a packageManager field. It tells Corepack which manager and version to use, which keeps a team consistent.
{
"packageManager": "pnpm@9.0.0"
}
Common mistakes
Two lockfiles in one repository. The install depends on which command was run.
npm install in CI. It may update the lockfile and resolve a different version. Use npm ci.
A lockfile that is not committed. The build resolves a different tree than the one that was tested.
Assuming a package works because it installs. A phantom dependency works under npm and fails under pnpm. Test with the manager the consumer will use.
Mixing managers in a monorepo. One package with npm and another with pnpm produces two stores and two lockfiles.
Ignoring the lockfile diff in a review. A transitive dependency change is often the cause of a subtle break.
A quotable summary
npm, Yarn and pnpm all install from the same registry and read the same package.json, and they differ in storage, strictness and speed. pnpm uses a content-addressable store and hard links, so it uses the least disk and is usually the fastest for a cold install, and its strict layout surfaces a phantom dependency that npm and Yarn hide. Commit exactly one lockfile, use the frozen install in CI, and prefer consistency over the choice of manager.
Related reading
For the manifest, see package-json-explained and for the modules, javascript-modules-guide. For the broader context, monorepo-vs-multirepo and dependency-vulnerability-scanning.