pnpm: one copy of every package, for all your projects
pnpm is a package manager for Node.js — the tool that downloads and places the libraries your program uses. Instead of keeping a copy of every library inside every project, it keeps one copy in a shared place and gives each project a link to it. Your disk stops filling up with the same files, and your code can no longer run on libraries it never declared.

In two words first
Picture a street of ten houses, each with a library of the same two hundred books. Nobody borrows from a neighbour; everyone buys their own copy. The shelves fill up, the duplicates multiply, and every time a new edition comes out it has to be bought ten times.
pnpm builds one library for the whole street. Each book exists once, in a shared place. The houses do not take a copy; they take a link — a label saying "that book is over there". Each shelf looks complete, but the paper on the disk is one set, not ten.
That shared place is called the store, and the folder that fills up inside your project is called node_modules — the spot where Node.js looks for libraries when your program asks for one. It is famous for its size: thousands of files, hundreds of packages, and the same work copied into every project folder.
There is a second half to this that does not show at first glance, and it is, to my mind, the more useful one. The old way puts every library's own dependencies at the top level of node_modules too — a flat pile of packages you never asked for. Your code can then reach into that pile, use something it never declared, and work. It works today; tomorrow, when the library changes version and the package leaves the pile, your code breaks, and you hunt a bug caused by something you never wrote.
pnpm shows you only what you declared. If it is not in package.json — the file where a Node.js project records what it needs — require() fails with MODULE_NOT_FOUND. That is not a defect: that is the tool doing its job.
So two things to take away: less space on disk, and more discipline in your dependencies.
What it does
pnpm is a package manager: it installs, removes, upgrades and tidies the libraries a Node.js project uses. It does what npm does, with a different logic about where files live.
First, it keeps a lockfile — the file pnpm-lock.yaml, which records the exact version of every package installed, together with its dependency tree. A lockfile locks versions: two machines, two colleagues, two runs in CI all pull exactly the same packages. Without it, an install from March and one from November may not resemble each other at all, and the bug shows up for neither.
Second, it keeps a shared store: every package is downloaded once to disk, and from then on every project on the machine points there. Installing the same package again downloads nothing and copies nothing.
Third, it supports workspaces: one repository holding several packages that share dependencies and commands. The word you meet for this is monorepo — "one repository, many programs" — and this is where the shared store matters most, because ten packages using the same tool do not keep ten copies of it.
Fourth, in CI pipelines — the automated sequences that run on every code change — it gives stable installs: it reads the lockfile, it does not guess versions, and it can cache the store between runs. In practice the "install dependencies" step drops from minutes to seconds, with exactly the same packages.
Fifth, it has settings for the shape of node_modules. The important one is node-linker — how it builds the folder. By default it uses links and a layout that keeps every package close to whoever declared it; with node-linker=hoisted it builds a flat folder like npm's, for tools that do not know how to work otherwise. It is a compatibility switch, not a better practice.
What it does not do
It is not a runtime. It does not execute your code and does not replace Node.js; it stops at managing the library files. Whatever runs your program is Node.
It does not fix tools that expect a flat node_modules. Some programs and plugins look for a library at the top level of the folder, because that is how they found it for years under npm. With pnpm that may not work, and then you enable hoisting — moving dependencies upwards so they appear at the top level — with node-linker=hoisted or the --shamefully-hoist flag. The name of the second one says it all: it is a concession, and it loosens the strictness that is the whole point.
It does not hide other packages' mistakes. If a package asks for a library it never declared, you will see MODULE_NOT_FOUND — not because pnpm is harsh, but because the previous manager was covering for it. The defect was always there; pnpm simply stops hiding it. The fix is one line in your project's package.json.
It is not a deployment tool. It can help you build smaller Docker images — the packages that run in production — but containers, image registries and the production pipeline remain the job of other tools.
It is not "npm under a different name" in every respect. It is not a drop-in: it changes where files live, and therefore what your code sees. In a project that has worked for years with a flat folder, the move deserves a review pass, not a pnpm install and hope.
How to use it
You install pnpm once on the machine:
npm i -g pnpm
If your Node is recent, there is also the Corepack route, which needs no global install:
corepack enable
Then you work inside your project folder. To start a new project:
pnpm init -y
To add a library:
pnpm add express
To install everything recorded in package.json and the lockfile — the command you run on every new machine and in every CI:
pnpm install
For a tool you only need while writing code (tests, type checking, formatting):
pnpm add -D typescript
To run a command you defined in package.json:
pnpm run build
And to clean out of the shared store whatever no project uses any more:
pnpm store prune
The flow is simple: init, add, install, run. Whatever npm does, pnpm does with the same vocabulary.
Driving it from the shell — and why it is not MCP
pnpm is not an MCP server: it is not a service you declare to an assistant so it can call it, nor something running in the background. It is a command-line tool with subcommands — you call it from the terminal, it finishes, it goes away. There is nothing to declare anywhere, and you pay nothing in context load for it: the model carries no schema of it at all.
If you drive it from an automation or an assistant, two commands are enough:
pnpm install --frozen-lockfile
and
pnpm run <script>
The first says "install exactly what the lockfile says, and if it does not match package.json, stop with an error" — that is what you want in CI, because a silent version change inside a pipeline is worse than a red step. The second runs whatever task you defined in your project.
For a single library, without adding it to the project, there is pnpm dlx, the sibling of npx. Nothing else is needed — no server, no configuration.
Our hands-on test
We did not take these numbers from the tool's page; we measured them. We set up a clean project, added express@4.21.2 — one of the most widely used Node server libraries — and ran the same install twice, once with npm and once with pnpm.
The first finding is visible at a glance. npm spread 67 packages across the top level of node_modules. pnpm left one: only the express we declared. The other sixty-six are there — inside the shared store, in a layout that keeps them reachable only to whoever declared them.
The second finding is our trap, and it is the most useful part of this article. We wrote a small program asking for require('ms') — a library nobody declared, but a dependency of express. With npm the program works: it finds the ghost in the flat pile. With pnpm it fails with MODULE_NOT_FOUND. Same code, same project, same library — and the difference is not a pnpm defect: it is proof that the code rested on something it had never declared.
The third number is about disk. We set up three projects with the same dependencies. Under npm they took 11 MB; under pnpm 6 MB, because the files are shared from the store instead of being duplicated. To be fair, let us say it the other way too: in a single project the difference was negligible — around 3 to 4 MB either way. The gain begins as projects multiply.
The fourth is time, and here I want to be precise because it is easy to oversell. With warm caches, on the same machine, npm took 9.1 seconds and pnpm 6.3 for the same project. That is one measurement, not a benchmark; install times move a great deal with the network and the moment. I keep it as an indication, not a promise.
From the registries, for the tool's identity: latest version 12.18.0, published 5 November 2026; licence MIT; the engines field asks for Node 18 or newer; zero regular dependencies and 14 optional ones, which are per-platform binaries; package size 4,426,497 bytes, about 4.4 MB; and 325,920,735 downloads a week. On GitHub the repository has 37,047 stars, 1,985 forks and 198 open issues, with a first commit on 28 January 2016 and activity today.
What it costs
The tool is free: MIT licence, no subscription, no usage limit. What you pay, you pay in your own machine's resources.
In space. The package itself downloads 4,426,497 bytes — about 4.4 MB — with zero regular dependencies, meaning it brings no other packages with it. The 14 optional dependencies are per-platform binaries, and only the one matching your system is fetched. Our own measurement: three projects with the same dependencies took 11 MB under npm and 6 MB under pnpm.
In time. Our own measurement, warm caches: 9.1 seconds with npm, 6.3 with pnpm, for the same project. One measurement, not a benchmark — time depends heavily on the network.
In model context (tokens). Zero fixed cost. It is not an MCP server, it is declared nowhere, and the model carries no tool schema for it. If an assistant uses it, the cost is the same two commands it would send anyway.
In effort, which is not free. pnpm requires you to declare whatever you use. In a new project that is a gift; in a project that has long rested on undeclared libraries it is one-time work — and you measure it by how many MODULE_NOT_FOUND errors the first run prints.
One honesty note: everything we say here about speed and space is measured by us, but the vendor's own promise for large monorepos we did not test — we did not set up ten packages in one repository. We say so, rather than passing it off as established.
When it is worth it
It is worth it, first, when you have many projects with shared dependencies, or when you work in a monorepo. There the shared store is not a detail: ten packages using the same tool do not keep ten copies of it, and matching versions between packages becomes something the tool handles.
It is worth it, second, when you want stable installs. pnpm-lock.yaml locks versions, and together with --frozen-lockfile it makes CI stop when something does not match, instead of serving a different build from the one you tested.
It is worth it, third, as a mirror: it shows you which libraries your code uses without ever declaring them. Anyone who has worked on a project that broke during a refactor knows how expensive that knowledge is.
It is less worth it when the project is a single small one, or when it rests on old tools that expect a flat node_modules: there the space gain is small and the cost in --shamefully-hoist and in testing can outweigh it. And it is not a tool for anyone who does not want to know what their project pulls in — its strictness is precisely the opposite of comfort.
Final word
pnpm is mature and practical. It keeps one copy of every package and gives each project a link to it; it does not let you work with libraries you never declared; and in the registries it carries the weight of a tool used every day — 37,047 stars, 325 million downloads a week, a release published five days ago.
If you try it the way we tried it, you will judge it in ten minutes: one project, two installs, two folders, one look at the size and one at the MODULE_NOT_FOUND. The difference will not be an impression — it will be numbers, and you will know whether it suits you.
Sources: