What happens when you delete `node_modules` on a Friday afternoon, run a fresh install, and watch your laptop fan spin up like a jet engine? For most JavaScript developers, that moment is the first real reason to care about the pnpm vs npm question. Both tools pull packages from the same registry. Both read the same `package.json`. Yet they behave differently enough that switching one for the other can break a build, shrink a CI pipeline, or quietly fix a bug you never understood.
This comparison focuses on workflow. Not benchmarks you’ll forget by Monday, but the day-to-day differences in disk layout, lockfiles, dependency resolution, and continuous integration that shape how a team actually ships code.
Why the npm vs pnpm debate keeps resurfacing
npm ships with Node.js, so it wins by default. Most developers learn it before they learn anything else, and that inertia is powerful. pnpm, first released in 2017, took a different architectural path and has been steadily pulling teams toward it ever since.
The core distinction is simple to state. npm copies packages into each project’s `node_modules`. pnpm stores every package version once in a global content-addressable store and links it into projects that need it. The pnpm documentation on the store and linking model explains this design in detail, and it is the root cause of nearly every other difference covered below.
That single design choice cascades into install speed, disk usage, how dependencies resolve, and how much trust you place in your dependency tree. Understanding the cascade is more useful than memorizing a feature table.
Disk layout: flat and hoisted versus strict and linked
This is the difference that bites people first, usually in the form of a mysterious “module not found” error after a migration.
npm flattens the dependency tree. It hoists packages upward into `node_modules` to deduplicate them, which is why an undeclared dependency often resolves anyway. If your code imports `lodash` without listing it in `package.json`, npm will frequently let that slide because some other package already pulled it in. The official npm documentation on the folder structure describes this hoisting behavior. (npm (software)))
pnpm does not flatten by default. Only your direct dependencies appear at the top level of `node_modules`; transitive dependencies stay nested. The pnpm guide to the symlinked node_modules structure walks through the resulting tree. In practice, this means pnpm surfaces phantom dependencies immediately. Code that worked under npm may fail under pnpm because it was never actually declared.
That failure is a feature, not a bug. Phantom dependencies are a real hazard: they make builds fragile, because a dependency of a dependency can disappear in a patch release and take your app with it. pnpm forces the honesty npm tolerates.
| Behavior | npm | pnpm |
|---|---|---|
| Default layout | Hoisted, flat | Non-flat, symlinked |
| Undeclared imports | Often resolve | Usually fail |
| Package storage | Copied per project | Global store, hard-linked |
| Phantom dependency risk | Hidden | Exposed early |
| Escape hatch | None needed | `node-linker=hoisted` |
That last row matters for migrations. pnpm offers a hoisted compatibility mode for tools that assume npm’s flat layout, and it is documented among the pnpm npmrc settings. When a legacy build tool refuses to cooperate, this setting is the pressure valve.
Install speed and disk usage in practice
The store-based model pays off most on machines with many projects. Ten repositories that share React, TypeScript, and a testing stack will each carry their own copy under npm. Under pnpm, those versions live once in the store and get linked. The savings compound quickly on a developer laptop with a small SSD.
CI runners feel it differently. A cold npm install downloads and extracts everything. A pnpm install can restore the store from cache and link from there, which is usually faster, though the gap narrows on warm npm caches. The honest framing: pnpm’s advantage is largest on cold installs and multi-project machines, and smallest on a single small project with a hot cache.
A practical tip that saves real time: run `pnpm store path` to find the store location, then cache that directory in CI rather than caching `node_modules`. Caching `node_modules` across pnpm versions is a classic mistake, because the symlink structure can go stale and produce confusing resolution errors. If you are already tuning your developer environment, the same instinct applies to other tooling decisions, as covered in this comparison of Obsidian vs Logseq local-first notes compared by workflow and this breakdown of Dropbox alternatives by use case that actually fits your workflow. The pattern is the same: pick the tool whose default behavior matches how you actually work.
Lockfiles, peer dependencies, and the migration trap
Lockfiles are where careless teams get hurt. npm writes `package-lock.json`. pnpm writes `pnpm-lock.yaml`. They are not interchangeable, and the npm package-lock documentation makes clear that the format is npm’s own.
Mixing them in one repository is the single most common migration mistake. Someone runs `npm install` on a branch, someone else runs `pnpm install`, and now two lockfiles describe two different trees. CI picks whichever it finds first. Builds pass locally and fail on the runner. The fix is boring but non-negotiable: commit one lockfile, delete the other, and add the losing tool to your CI guardrails.
Peer dependencies are the second trap. npm 7 and later auto-install peers, which makes many setups “just work.” pnpm’s peer handling is stricter by default, and its defaults have shifted across major versions, so behavior depends on which pnpm release you target. Before a migration, read the pnpm npmrc reference for your exact version rather than relying on a blog post from two years ago. Version-specific defaults are where most migration advice goes stale.
Workspaces and monorepos
Monorepo setup differs in configuration, not philosophy. npm uses a `workspaces` field inside the root `package.json`, described in the npm workspaces documentation. pnpm uses a separate `pnpm-workspace.yaml` file, explained in the pnpm workspaces guide.
The pnpm approach is more explicit. You list package globs in a dedicated file, and workspace protocol references (`workspace:*`) make internal dependencies obvious in `package.json`. Teams that have been burned by accidental registry installs of an internal package tend to prefer this. Teams with simple two-package repos often find npm’s inline field less ceremony. (package.json)
Neither is objectively better. The question is whether your monorepo benefits from explicit boundaries. If internal packages are frequently confused with published ones, pnpm’s explicitness earns its keep.
CI pipelines and caching strategy
Continuous integration is where workflow differences turn into money. A slow install multiplied by hundreds of pipeline runs a month is a real budget line.
The practical setup for pnpm in GitHub Actions uses the `setup-node` action with pnpm caching enabled, documented in the actions/setup-node repository. That handles store caching without custom scripts. npm has its own caching path through the same action, and it works well, but it caches the npm cache directory rather than a shared store.
Three habits that prevent most pnpm CI pain:
- Pin the pnpm version in CI with a `packageManager` field or an explicit setup step, so the runner and developers use the same release.
- Cache the pnpm store, never `node_modules`.
- Run `pnpm install –frozen-lockfile` in CI so a drifted lockfile fails fast instead of silently resolving new versions.
The third habit is the one teams skip and later regret. It converts a class of “works on my machine” bugs into an immediate, readable CI failure.
Common mistakes when switching from npm to pnpm
Migration failures cluster around a few predictable causes. Knowing them in advance saves an afternoon.
Deleting `node_modules` but not the old lockfile. The install then reconciles against stale data. Remove both, then install fresh.
Assuming hoisted behavior. Tools that scan `node_modules` for plugins, older bundler plugins, and some native build scripts expect a flat tree. Either declare the missing dependencies properly or enable hoisted mode temporarily while you fix the root cause.
Skipping the phantom dependency audit. Before switching, run a quick check for imports your `package.json` never declared. pnpm will find them for you, but finding them on your schedule beats finding them during a release.
Forgetting editor and tooling integrations. Language servers, test runners, and linters sometimes need a restart or a workspace re-index after the layout change.
Ignoring peer dependency warnings. pnpm’s stricter peer resolution surfaces conflicts npm papered over. Read the warnings instead of silencing them.
If you are the kind of person who tunes tooling carefully, the same discipline shows up elsewhere, such as in this guide to the keyboard foam mod sound differences it actually changes or this walkthrough on how to disable Copilot in Windows 11 without breaking your workflow. Small configuration choices have outsized effects on daily friction.
What to expect looking toward 2027
Any claim about exactly what npm and pnpm will look like in 2027 is projection, not documented fact. Neither project has published a verified roadmap that far out, and treating a forecast as a certainty is how teams make bad bets.
What is reasonable to expect, based on current trajectories:
- Convergence on the registry, divergence on layout. Both remain npm-registry clients, so `package.json` semantics stay shared. The layout and resolution differences will likely persist because they are architectural, not incidental.
- Stricter defaults everywhere. The ecosystem has been moving toward explicit dependency declaration for years. pnpm’s strictness is a preview of where the broader tooling conversation is heading.
- Better CI integration on both sides. Caching and reproducibility features keep improving in both tools, which is good news regardless of which you pick.
The practical takeaway for planning: choose based on your team’s tolerance for strictness today, not on a guess about 2027. If your codebase has phantom dependencies and you want them gone, pnpm’s defaults do the work for you. If you depend on tooling that assumes a flat tree and migration cost is high, npm remains a perfectly defensible choice.
Which should a team pick?
A short decision guide, honestly stated:
| Situation | Sensible default |
|---|---|
| Small project, single developer | npm, for zero setup |
| Many projects on one machine | pnpm, for store savings |
| Monorepo with internal packages | pnpm, for explicit workspaces |
| Legacy tooling needing flat layout | npm, or pnpm in hoisted mode |
| CI cost is a pain point | pnpm, with store caching |
| Team unfamiliar with strict resolution | npm first, migrate later |
There is no universal winner. There is only the tool whose defaults match your constraints. The worst outcome is running one tool locally and another in CI, which is how lockfile drift becomes a recurring incident.
Conclusion
The pnpm vs npm question is really a question about defaults. npm optimizes for compatibility and zero-config onboarding, which is why it remains the safe starting point for most projects. pnpm optimizes for correctness and efficiency, which is why teams with many repositories, monorepos, or a strong interest in reproducible builds keep moving toward it.
The differences that matter in 2027 will not be benchmark numbers. They will be the quiet ones: whether your dependency tree is honest, whether your lockfile is singular, whether your CI caches the right directory, and whether your team understands the resolution model it depends on. Get those four right and either tool will serve you well. Get them wrong and no installer will save you.
Pick deliberately, migrate once, and commit the lockfile.
FAQ
Is pnpm faster than npm?
Usually yes on cold installs and on machines with many projects, because packages are stored once and linked rather than copied. On a single small project with a warm npm cache, the difference is often negligible. Speed is the least interesting reason to switch; dependency correctness matters more.
Can I use pnpm and npm in the same repository?
You can, but you should not. They write different lockfiles, and running both causes the dependency tree to drift between developers and CI. Pick one, commit its lockfile, and remove the other.
Why does my code break when I switch from npm to pnpm?
Almost always because of phantom dependencies. npm’s hoisted layout lets undeclared imports resolve; pnpm’s strict layout does not. The fix is to declare the missing packages in `package.json` rather than disabling strictness.
What is hoisted mode in pnpm?
It is a compatibility setting that makes pnpm produce a flat `node_modules` similar to npm’s layout. It exists for tools that assume hoisting. Use it as a temporary bridge during migration, not as a permanent default, because it gives up the strictness that makes pnpm valuable.
Do npm and pnpm use the same registry?
Yes. Both are clients for the public npm registry and share `package.json` semantics. Switching package managers does not change what you publish or how consumers install your package.
How do I migrate a monorepo from npm to pnpm safely?
Remove `node_modules` and `package-lock.json`, add a `pnpm-workspace.yaml` listing your package globs, run a fresh install, fix every phantom dependency it surfaces, then update CI to cache the pnpm store and install with a frozen lockfile. Do it on a branch and let CI prove the migration before merging.
