pnpm 12.22.0 adds a globalPackagesConfig section to the global config.yaml for settings that apply only to global packages, adds pnpm why --ranges, and lists workspace projects in dependency order in pnpm list --recursive. It also includes a security fix. After the default or a scoped registry changed, pnpm install could skip the minimumReleaseAge and trustPolicy checks against the new registry.
Minor Changes
-
Settings under
globalPackagesConfigin the globalconfig.yamlnow apply only to commands that act on global packages, such aspnpm add -gandpnpm update -g. For example,globalPackagesConfig.trustPolicyExcludeexcludes a package from the trust policy for global installs only #18130.pnpm approve-builds -gandpnpm add -g --allow-buildnow save build decisions underglobalPackagesConfig.permissions. pnpm still applies build settings from thepnpm-workspace.yamlof the global packages directory, with a deprecation warning. The next approval moves them toconfig.yaml. -
Added
pnpm why --ranges, which lists the version range that each direct dependent declares for the package.pnpm why --jsonnow includes the declared range of each dependent in arequiresfield #18121. -
pnpm list --recursivenow lists workspace projects in dependency order. Use--no-sortto retain workspace order #7716. -
A
file:dependency on a local directory now resolvescatalog:specifiers in that directory'spackage.jsonagainst the workspace catalogs, as an injected workspace package does. Before, the install failed withERR_PNPM_SPEC_NOT_SUPPORTED_BY_ANY_RESOLVER.A
file:dependency on thepublishConfig.directoryof a project is now described by that project'spackage.json, as an injected workspace package is. Apackage.jsonthat a build writes into that directory no longer changes the resolution. -
The experimental
v13lockfile format records a local directory package's declared specifiers in itsdependenciesandoptionalDependencies, beside the versions they resolved to. A dependency markedinjectedindependenciesMetahasinjected: true. The format no longer has adependenciesMetafield. Runpnpm installto rewrite av13lockfile that an earlier pnpm wrote.
Patch Changes
Security
-
pnpm installnow re-verifies lockfile resolutions when the default registry or a scoped registry changes. Before, it reused the result cached for the previous registry and skipped theminimumReleaseAgeandtrustPolicychecks against the new one #18070.For a registry with
serverType: pnpr,pnpm installalso verifies locked package revisions against the registry when no cached result applies. -
pnpm dlxno longer reuses a cached install made under looseroverrides,packageExtensions,minimumReleaseAge,trustPolicy,trustLockfile, orblockExoticSubdepssettings. It also no longer appliesoverrides,packageExtensions, orblockExoticSubdepsfrom a localpnpm-workspace.yaml#18075.pnpm dlx --allow-build=!<pkg>now denies build scripts for<pkg>, including the executed package itself. Denied packages also skip interactive build approval. -
pnpm auditnow reports advisories whoseidis a string. Such advisories were dropped, andpnpm auditreported no known vulnerabilities #18184.
Installs that failed
-
When the
pnpmpackage downloads its native binary on first run, it now reads a globalconfig.yamlthat holds only blank lines or comments as no settings. Such a file made every command fail with "expected a document, but the input is empty" #18172. -
When the
pnpmpackage downloads its native binary on first run, it now works with registries that serve no per-version package documents, such as Azure Artifacts. If such a registry also removed npm's signatures, pnpm fetches them from registry.npmjs.org. The binary still comes from the configured registry and is checked against npm's signature. -
Fixed an offline install failing the
minimumReleaseAgelockfile check withERR_PNPM_NO_OFFLINE_METAafter an online install resolved the same packages with the same cache directory. The check now reads publish times from the metadata that the resolution cached #18063. -
pnpm installno longer runsgit ls-remotefor a git dependency whose specifier is unchanged and whose commit the lockfile already records. Installs that update the lockfile, such as Renovate's, no longer fail without git credentials when the project has a private git dependency with peer dependencies #18104. -
npm:<pkg>@<range>and named-registry package aliases with space-separated comparators, such asnpm:bar@>=1.0.0 <2.0.0, now resolve the target package #18169. -
pnpm installwithlockfile.format: v13no longer fails withERR_PNPM_NEXT_LOCKFILE_NOT_REPRESENTABLEwhen it converts av9lockfile in which a package with many peers has a hashed peer suffix and is in a dependency cycle with one of its peers #18148. -
pnpm deploy --prodnow succeeds withlockfile.format: v13when a production package's optional peer is provided only by development dependencies. The excluded provider stays out of the deployed project #18117. -
pnpm deploynow preserveslockfile.formatandlockfileIncludeTarballUrlin the deployedpnpm-workspace.yaml. Previously, commands such aspnpm dedupe --checkin a deployed project usinglockfile.format: v13treated the lockfile asv9and reported changes. -
Fixed
pnpm install --merge-git-branch-lockfiles --frozen-lockfilefailing withERR_PNPM_OUTDATED_LOCKFILEwhen a project sets or removespublishConfig.directory,publishConfig.linkDirectory, ordependenciesMeta. Lockfile merging now preserves and reconcilespublishDirectory,linkDirectory, anddependenciesMetaon importers. -
Frozen installs accept injected workspace packages whose child dependencies use
link:or a bare relative path pnpm/tasks#274. -
Installing an injected local package no longer fails with a "no such file or directory" error when another process renames or removes files in that package while pnpm lists them. This happened most often on macOS in workspaces with
sharedWorkspaceLockfile: false, where the install of the package itself writes its lockfile at the same time. -
Fixed a crash when
pnpm-lock.yamlor a dependency selector contains a package name that starts with a multi-byte UTF-8 character. -
Tarball URLs that reject HEAD requests with 405 Method Not Allowed now fall back to a GET request during resolution.
Resolving and linking dependencies
-
With
autoInstallPeers, an optional peer is no longer bound to a version outside its range that only another dependency's subtree brings in. Before, adding an unrelated dependency could flip that binding and rewrite the peer suffixes of other projects in the lockfile #18162. -
Fixed duplicate packages with
nodeLinker: hoistedandautoInstallPeers: falsewhen identical transitive peer bindings appeared under parents with conflicting dependencies. -
When multiple
overridesselectors match a dependency, pnpm now picks the selector with the narrower version range regardless of the order in which the overrides are declared #18071. -
Patches that add lines to the end of a file without a final newline now install the whole file. pnpm dropped the last added line when the patch also marked it with
\ No newline at end of file#18156. -
Project
engines.nodechecks now use the Node.js runtime that pnpm links for the dependency groups being installed. If the lockfile records that runtime, the check uses its resolved version. Production installs ignore a runtime declared only indevEngines.runtimepnpm/tasks#302. -
pnpm installandpnpm approvenow discover, link, and prune agent skills fromworkspace:*,link:, and local directoryfile:direct dependencies.
Cargo and Python
-
pnpm add crate:and targetedpnpm update crate:commands keep compatible versions fromCargo.lockfor other crates pnpm/tasks#257. -
pnpm add crate:<pkg>no longer corrupts multiline arrays inCargo.toml. Saving an explicit version withpnpm add crate:<pkg>@<version>now replacesworkspace = trueon existing dependency entries. Inherited workspace settings such asfeatures,default-features, andpackagestay on the updated entry.pnpm installnow accepts unversioned path dependencies on prerelease Cargo workspace members. Cargo workspace inheritance now resolvespackagerenames. -
pnpm addforpypi:dependencies now preserves existing entries inpyproject.tomlwhose PEP 508 environment markers differ from the added requirement.pnpm addalso accepts PEP 508 direct URL requirements such aspypi:pkg @ https://....pnpm updateat a shared-environment workspace root without a root[project]table now updates matching member manifests and the sharedpylock.toml. -
An invalid entry in a Python registry's
packageslist now names the patterns a Python registry accepts: an exact name, a prefix such ascompany-*, or**. The error used to suggest@scope/*, which a Python registry rejects. It also quotes the entry as written. A rejected prefix such as-a*used to appear as-ax.
Running scripts
-
verifyDepsBeforeRunno longer reports the dependencies as out of date whenruntimeOnFailstops pnpm from installing the runtime thatdevEngines.runtimeorengines.runtimedeclares #18155.Commands that install a single project of a workspace, such as
pnpm add -w, now applyruntimeOnFailto the other workspace projects too. They no longer install a runtime thatruntimeOnFailexcludes. -
pnpm --if-present start,pnpm run --if-present start, andpnpm restart --if-presentnow exit with code 0 when a project has neither astartscript nor aserver.jsfile #18073. -
pnpm test,pnpm t, andpnpm tstin a single-package project now fail withERR_PNPM_NO_SCRIPTwhen thetestscript is missing unless--if-presentis passed #18073. -
shellEmulatornow handles escaped backslashes (\\) and unquoted escaped single quotes (\') according to POSIX quoting rules. Previously, scripts containing"a\\"or\'failed to parse or misquoted later${...}parameter expansions. -
pnpm createnow forwards--env-fileand other CLI flags placed after the starter template name to the starter command. -
pnpm pipelinenow hashes no input files wheninputs: []is configured.+-prefixed input globs include gitignored files and workspace files outside the project directory.!-prefixed input globs exclude matching files. Tasks that depend on an uncacheable task now bypass cached output restoration and re-run after that dependency executes. Read-only cached output files restore without permission errors. Task keys now hash each project's wanted lockfile across per-project lockfiles, customlockfileDir, and branch lockfiles.
Build approvals
-
pnpm approve-buildsandpnpm approvewithout package arguments or--allnow fail withERR_PNPM_APPROVE_BUILDS_NON_INTERACTIVEandERR_PNPM_APPROVE_NON_INTERACTIVEwhen packages are awaiting approval in CI or without an interactive terminal.pnpm dlxand global installs also skip automatic build-approval prompts in CI, leaving pending builds unapproved. -
pnpm approve-buildsandpnpm add --allow-buildno longer corrupt apnpm-workspace.yamlwhose last line has no line break.
Workspaces and lockfiles
-
Combining
--filterand--filter-prodwith exclusion selectors such as!pkgnow evaluates all selectors together in command-line order. An exclusion passed on one flag while inclusions were passed on the other no longer selects every workspace project. -
pnpm -r fetchnow fetches each selected project's lockfile whensharedWorkspaceLockfileisfalse. Use--filterto limit which projects are fetched #18152. -
pnpm peersin workspaces withsharedWorkspaceLockfile: falsenow checks each selected project'spnpm-lock.yaml. -
pnpm cinow validates thatpnpm-lock.yamlexists and matchespackage.jsonbefore removingnode_modules.pnpm cleanandpnpm cinow honor--filter,--filter-prod, and--workspace-root.pnpm cleanandpnpm cialso clean rootnode_modulesin workspaces without a rootpackage.json.pnpm clean --lockfilenow removes per-project lockfiles and lockfiles inside a customlockfileDir. -
pnpm clean,pnpm purge, andpnpm cikeep files outside the project untouched whenmodulesDirpoints outside the project root. Whennode_modulesis a symlink,pnpmnow unlinks the symlink without modifying its target #18072. -
pnpm importnow preserves locked versions fornpm:aliased dependencies when importing frompackage-lock.json,npm-shrinkwrap.json, oryarn.lock.pnpm importalso parses Yarn Classicyarn.lockfiles that reference__metadatapackage names without treating them as Yarn Berry lockfiles.
Updating, publishing, and versioning
-
pnpm updatenow moves anengines.pnpmrange along with the pnpm version inpackageManagerordevEngines.packageManager#18142. -
Fixed GitHub Actions support in
pnpm updateandpnpm outdated. Updating a workflow step with a major or minor version comment such as# v4or a prose comment now formats the updated version comment cleanly. Negated action selectors such as!actions/cache/savenow exclude only the targeted subpath actions. Passing only negated action selectors still updates packages. Previously, negated action selectors skipped package updates.pnpm outdatednow reports every distinct outdated version when several workflows pin the same action at different versions. -
Fixed
pnpm updateskipping package updates when a Package URL selector such aspkg:npm/foois combined with--include-github-actions. -
pnpm update -g --latestnow upgrades global runtimes (node,deno, andbun) andnpm:-aliased global packages across major versions. -
pnpm update --changesetnow generates a changeset when a.changesetdirectory exists orversioningis configured inpnpm-workspace.yaml, without requiring.changeset/config.json. It also respectsversioning.ignorealongside.changeset/config.json. -
pnpm version -rnow runs each bumped package'spreversion,version, andpostversionscripts unless--ignore-scriptsor--dry-runis set.pnpm version -r --dry-run --jsonnow prints the planned releases as a JSON array. -
pnpm lane <lane> --filter <selector>now rejects partial moves of aversioning.fixedgroup withERR_PNPM_VERSIONING_CONFLICTING_CONFIGbefore writingpnpm-workspace.yaml. -
pnpm -C <dir> publish <tarball|folder>andpnpm --dir <dir> publish <tarball|folder>now resolve relative tarball and directory arguments against<dir>. Git checks duringpnpm publishalso inspect the target directory. -
pnpm -r publishnow skips workspace manifests whosenameorversionfield is an empty string. -
pnpm -r pack --outnow expands%sand%vplaceholders only in the--outtemplate. Literal%sand%vsegments in the working directory path stay unchanged.
Other commands and settings
-
pnpm config set --global --json toolsnow writestoolsto the globalconfig.yamland validates its structure before saving.pnpm config set --globalalso acceptspm-on-failandruntime-on-fail.blockExoticSubdepsandexcludeLinksFromLockfileset in the globalconfig.yamlnow take effect during installs and appear inpnpm config get --global. pnpm now ignores workspace-only settings in the globalconfig.yamland prints a warning, matchingpnpm config set --global. -
${VAR}placeholders inpnpm-workspace.yamlwritten with YAML flow syntax now fail on registry URLs withERR_PNPM_REGISTRY_ENV_NOT_EXPANDED. Placeholders in flow-style proxy,pnprServer, anduserAgentsettings are now ignored with a warning #18074. -
updateConfigandafterAllResolvedhooks in.pnpmfile.cjsthat returnundefined,null, or a non-object value now fail withERR_PNPM_CONFIG_IS_UNDEFINEDandERR_PNPM_BAD_AFTER_ALL_RESOLVED_RETURN. -
findersin.pnpmfile.cjsthat return an empty string no longer match packages inpnpm list --find-byorpnpm why --find-by. -
pnpm listno longer adds annpm:prefix to aliased localfile:directory dependencies, andpnpm list --jsonpreserves<name>@file:<path>in theirversionfield. -
pnpm list --parseable --longnow keeps<name>@onlink:andfile:dependencies whose path or peer suffix contains@, such aslink:../@scope/pkg. Aliased scopedfile:dependencies whose path contains@also keep<name>@inpnpm list. -
pnpm whyno longer merges distinct localfile:directory dependencies that share the same package name across projects with dedicated lockfiles (sharedWorkspaceLockfile: false). -
pnpm sbomandpnpm licenses listnow resolvenamedRegistriesversion prefixes in lockfile entries.pnpm sbomemits bare component versions with a sanitizedrepository_urlPURL qualifier.pnpm sbomderives tarball download URLs from the named registry.pnpm licenses listreports packages from named registries as separate entries with bare versions andregistryName. -
pnpm pkgnow reads and writes the project manifest as written on disk.pnpm pkg getno longer reports syntheticruntime:dependency entries fromdevEngines.runtimeorengines.runtime.pnpm pkg setandpnpm pkg deletenow preservedevEngines.runtime,engines.runtime, and empty dependency objects set with--json. -
pnpm pmnow works after CLI flags such as--dirand afterpnpm with current.pnpm with currentalso accepts subcommand boolean flags such aspnpm --bare with current initahead ofwith. -
pnpm envcommands (use,list, andremove) now accept Node.js version specifiers with a leadingv, including prerelease versions such asv22.0.0-rc.1. -
pnpm doctornow checks write access for the cache, store, and global bin directories before they have been created. Previously,pnpm doctorreportedno write accesson fresh environments.pnpm doctornow probes whether reflinks or hardlinks work from the store into the project's link target and warns when neither does.
Output and error messages
-
An error from a failed dependency resolution, such as an unreachable registry or a throwing pnpmfile resolver, now prints its cause once #18077.
-
pnpm no longer wraps error messages at the output width, so URLs and paths in them stay intact when stderr is not a terminal #18078.
-
pnpm installwithnodeLinker: hoistedno longer counts missing packages as removed. This fixes inflated removal counts for skipped optional dependencies #18178. -
pnpm outdated --jsonandpnpm outdated --format=jsonnow write reporter warnings tostderr. Warnings previously appeared onstdoutbefore the JSON output. -
pnpm stagewith--jsonnow keepsstdoutvalid JSON during dry runs, empty workspace runs, and errors.pnpm pipeline --dry-run --jsonandpnpm -r run --dry-run --jsonnow write reporter warnings and scope lines tostderr. -
pnpmwarns when anupdateConfighook changesregistriesand some routes still use their configured registry. The warning names those routes and points toregistriesByScope. -
pnpm cat-filenow reportsERR_PNPM_INVALID_HASHwhen given an empty, malformed, or truncated digest such assha512-.
Platinum Sponsors
|
|
|
|
|
|
|
Gold Sponsors
|
|
|
|
|
|
|
|
|
|
|
|