pnpm
Performant npm
- Pronunciation
- pee-en-pee-EM
In short
pnpm is a fast, disk-efficient JavaScript package manager that keeps one copy of each package version in a shared store and links it into projects.
What is pnpm?
pnpm, short for performant npm, installs JavaScript packages from the same npm registry and reads the same package.json as npm. What it changes is where the files go. npm copies every dependency into each project's node_modules, so ten projects that use React hold ten copies of it. pnpm saves each file once in a content-addressable store, a folder where files are filed by a hash of their content, and adds it to every project that needs it as a hard link, a second name for the same file on disk, so the extra copies take almost no space and repeat installs are fast.
Its node_modules folder is built differently too. npm and Yarn Classic hoist, or lift, all packages to the top level of node_modules, so your code can import a package you never declared just because some dependency pulled it in: a so-called phantom dependency. pnpm puts only your direct dependencies at the top, as symbolic links into a hidden node_modules/.pnpm folder, so importing an undeclared package fails right away instead of breaking later.
pnpm writes its lockfile to pnpm-lock.yaml and has strong built-in support for monorepos: a pnpm-workspace.yaml file lists the packages, and --filter runs a command in only some of them. Since version 10, pnpm doesn't run the install scripts of dependencies unless you allow them, which closes a common route for supply chain attacks.
pnpm is sometimes taken for a fork of npm or a separate registry, but it is neither: anything published to npm installs with pnpm, and the commands are close (pnpm add, pnpm install, pnpm run). The difference is the install layout. Its strictness can expose hidden mistakes in older packages that relied on hoisting, and for those cases pnpm has settings that make the layout looser.
Key takeaways
- pnpm installs from the npm registry but stores each package version once and links it into projects.
- It saves disk space and makes repeat installs fast.
- Only declared dependencies are reachable, which prevents phantom dependencies.
- Workspaces and
--filtermake it popular for monorepos. - Since version 10, dependencies' install scripts run only if you allow them.
Example
pnpm install # install from pnpm-lock.yaml (npm install)
pnpm add react # add a dependency (npm install react)
pnpm add -D typescript # add a dev dependency
pnpm dlx create-vite # run a package once (npx create-vite)
pnpm --filter web build # in a monorepo, run "build" only in the "web" package
pnpm approve-builds # choose which dependencies may run install scripts
pnpm store path # show where the shared store is on diskReaders ask
Is pnpm faster than npm?
On repeat installs, usually yes: files already in the store are linked instead of downloaded and copied again. How much faster depends on the project and on whether the store is already filled.
What is a phantom dependency?
A package your code imports without listing it in package.json. It only works because another dependency installed it and the package manager hoisted it to the top of node_modules, so it breaks when that dependency changes. pnpm's layout makes such imports fail immediately.
Can I switch an existing npm project to pnpm?
Yes. pnpm import creates pnpm-lock.yaml from an existing package-lock.json or yarn.lock, and pnpm install does the rest. A few older tools that expect a flat node_modules may need pnpm's hoisting settings.
See also
- npmWeb Development, p. 38npm is Node.js's default package manager and the world's largest software registry; it downloads a project's dependencies and tracks their versions.
- YarnWeb Development, p. 72Yarn is a JavaScript package manager, an alternative to npm, that installs dependencies from the npm registry and adds a lockfile, workspaces and Plug'n'Play.
- Package ManagerProgramming Fundamentals, p. 47A package manager is a tool that installs, updates and removes software packages and their dependencies, resolving versions automatically.
- MonorepoVersion Control, p. 31A monorepo is a single version control repository that holds the code for many projects, such as several apps, services, and shared libraries, managed together.
- Node.jsBackend & APIs, p. 35Node.js is an open-source JavaScript runtime that runs JavaScript outside the browser, most often to build web servers, APIs, and command-line tools.
- Supply Chain AttackSecurity, p. 50A supply chain attack compromises software through something it relies on, like an open-source package, a build tool or an update server, not the app itself.
Sources
Spotted a mistake or something missing on this page?Suggest an edit