pnpm 12.21.0
TL;DR: pnpm 12.21.0 is a store-and-lockfile release. pnpm store add now prepares tarball and git dependencies for offline installs, repeated installs keep the peer dependency choices they made last time, and a pile of lockfile.format: v13, nodeLinker: hoisted, and pnpm deploy failures are gone. I've been running it on a monorepo with 14 workspace packages since Friday. Nothing exploded.
Dropped November 13, 2026, and this one is worth reading if you have ever stared at ERR_PNPM_BROKEN_LOCKFILE at 11pm.
The Actual Headline
pnpm store add inside a project now prepares downloaded tarballs for every lockfile entry that pins them. The release notes put it plainly: after that, pnpm install --offline --frozen-lockfile can install dependencies that point at a tarball URL, and dependencies on a git host such as GitHub whose lockfile entry records an integrity. Previously those went to the network no matter what your store already held.
If you build in an air-gapped CI image, this is your release. Prime the store on a machine with network, ship the store, install offline.
Peer Dependencies Stopped Wandering
The one that will save you the most debugging time: repeated installs no longer change the peer dependency providers the previous install chose. The notes list the cases: adding, updating, or removing a dependency, projects using different ranges of the same dependency, dependency cycles, and injected dependencies with autoInstallPeers: false.
An unchanged install now keeps a valid locked peer provider even when a direct dependency offers another compatible version. Explicit pnpm add and pnpm update still win, as they should. Two related fixes came along: workspace projects selecting different versions of a peer provider no longer share one copy of the package that depends on it, and a removed dependency no longer comes back from the dead as a peer provider.
With nodeLinker: hoisted plus autoInstallPeers: false, install no longer creates duplicate copies of a package whose resolved peers are identical.
Lockfile v13 and Deploy
The new lockfile format had a rough edge and 12.21.0 files it down:
- A lockfile mapping key longer than 1,024 characters, written as
'key':without the?marker, no longer fails install withERR_PNPM_BROKEN_LOCKFILE. - With
lockfile.format: v13, install no longer fails to create or rewrite the lockfile when a package declares many of its dependencies as peers. pnpm deploystopped failing with v13 when injected workspace packages have hashed peer bindings.- Frozen installs with v13 lockfiles accept valid peer dependencies of injected workspace packages that use catalogs.
- Injected workspace packages that depend on themselves no longer link to a directory that does not exist.
pnpm deploybinds optional peers declared only inpeerDependenciesMetafor linked workspace packages, and keeps them in the deployed manifest and lockfile when filtering dependency groups.
Frozen Store, Hono-Sized Details
With frozenStore enabled, install no longer dies with ERR_PNPM_FROZEN_STORE_NEEDS_BUILD when nodeLinker is hoisted. pnpm fetch with hoisted linking no longer populates global virtual store links or touches linked agent skills, and it now preserves an existing hoisted node_modules directory (issue #18037).
A requirements.txt sitting next to a pyproject.toml that declares [tool.uv.workspace] without a [project] table no longer turns that directory into a Python project. Before, install bailed there when the directory had a .venv pnpm did not create (issue #18023). Given the number of repos carrying both files, expect this to quietly unbreak a few pipelines.
Scripts, Shims, Pipeline
- Scripts stop when pnpm's process group is killed while they are starting.
- Bin shims in the global virtual store no longer carry the hoisted modules directory of the project that installed them (issue #18035).
pnpm pipelinerebuilds local packages and reruns build scripts after restoring a shared Cargo build cache with Cargo 1.100 or newer. Before, a worktree could reuse build-script output from the worktree that created the cache.pnpm setupand the install script support PowerShell as the login shell on Linux and macOS, addingPNPM_HOMEtoPATHinprofile.ps1under$XDG_CONFIG_HOME/powershellor~/.config/powershell(issue #18026).- A
lockfileDirpointing at the default lockfile directory behaves the same as leaving it unset.
pnpr Falls Back Locally
If the pnpr server refuses a setting the install uses, or cannot return the lockfile format pnpm reads, pnpm install and pnpm update now print a warning and resolve locally. Cargo and Python resolution do the same. pnpm also rejects a pnpr resolution of npm dependencies that does not name its lockfile format, limits the size of resolve and lockfile verification responses, and prints pnpr error codes and reasons when remote requests fail.
Upgrade
npm install -g [email protected], or corepack use [email protected]. The peer provider fix means your lockfile may change on the first install after upgrading, even with no dependency edits, if a previous install had already drifted. Commit that diff separately so you can tell it apart from real dependency work.
Full notes: pnpm 12.21.0.