Minor Changes#

• Added the sideEffectsCache.exclude setting for packages whose build depends on something pnpm cannot include in the cache key, such as the system libraries a native addon links against. pnpm builds the listed packages in every project and never restores or saves their builds through the side-effects cache, locally or on a remoteCache server. Under the global virtual store, each project gets its own copy of these packages and of the packages that depend on them. Entries use the same name, @scope/*, and name@version patterns as minimumReleaseAgeExclude #5271.

• pnpm login now prints the npm-notice response header during web-based login. Registries use it to show the verification code that completes the sign-in in the browser.

Patch Changes#

Installing packages#

• pnpm install and pnpm add no longer wait for the daily update check. If the command finishes first, pnpm skips the update notice and checks again next time. On a registry that accepted the connection but never answered, an install that had nothing to do used to take minutes #16839.

• pnpm install, pnpm add and pnpm update now reuse pnpm-lock.yaml when the workspace configures a catalog entry that no dependency references, such as an unused entry or one whose package an overrides entry replaces. Before, every resolution in such a workspace resolved all dependencies again from the registry #16923.

• pnpm install now looks up a git dependency's branch or tag once per install, even when many workspace projects depend on it. With linkWorkspacePackages enabled, it used to run git ls-remote once per project #16899.

• A filtered install, such as pnpm install --filter <pkg>, now keeps the pnpm-lock.yaml entries of workspace projects that are missing from disk, as in a sparse checkout. Their importers, packages, and catalog entries stay even when the filter matches every project on disk #16931.

• pnpm now decides whether a dependency that a package also declares as an optional peer is linked as a dependency or as a peer from the shallowest path that reaches the package. When an existing lockfile records such a dependency as a regular dependency and a newly added dependency now provides the peer, pnpm records it as a peer, as a fresh install does. The lockfile entry of such a package can change on the next install #16901.

• An install that adds nothing to the store no longer changes the modification time of the store directory. CI caches that check modification times, such as GitLab's, no longer re-upload an unchanged store #16929.

Running commands and scripts#

• pnpm no longer aborts with a core dump when the reader of its output has exited, as in pnpm list | head -1 or pnpm start 2>&1 | head -1. The command finishes with its usual exit code, and a failing script's exit code is kept. A write to stdout that fails for another reason, such as a full disk, ends the command with exit code 1 #16904 pnpm/tasks#132.

• On Windows, pnpm exec, pnpm run, and commands such as pnpm nx now return when the command they run exits, even if it left a detached process running and pnpm's output is redirected or piped. Previously a shell reading that output waited until the detached process, such as the Nx daemon, exited #16930.

• Commands that do not write the project manifest now leave a missing package.json absent. This covers queries such as pnpm why and pnpm outdated, pnpm fetch, pnpm dedupe --check, and commands that exit with an error, such as pnpm rt ls. These commands used to create one from the initialization template. pnpm sbom run from a lockfile alone now reports the root component as unknown with version 0.0.0 #16907.

• pnpm run now reports a failed script as a JSON record under --reporter=ndjson. It printed a plain [ELIFECYCLE] line to stderr.

• pnpm run no longer prints [ELIFECYCLE] Command failed with exit code N. to stderr when a script fails under --reporter=silent, --silent, or --loglevel=silent.

• pnpm pipeline --dry-run no longer writes a run report when no projects are selected. With --json it prints {"tasks": []} pnpm/tasks#126.

Packing and publishing#

• pnpm pack and pnpm publish now ship the whole gitignored directory that main, browser, or bin points into, as npm does. Previously only the main and bin files themselves were packed, and a gitignored browser file was left out #16908.

• pnpm pack and pnpm publish now honor a .npmignore or .gitignore inside a subdirectory when package.json has a files field. The package root's ignore files and those inherited from the workspace are still skipped #16909.

Setting up pnpm and toolchains#

• --registry, --https-proxy, --http-proxy, and --no-proxy now apply when pnpm resolves and downloads the pnpm version a project pins in packageManager. Before, these lookups went to https://registry.npmjs.org/, which a firewall that only allows a private registry blocks #16911.

• On Windows, pnpm install now installs the Rust toolchain for rustup's default host, so a machine set up with rustup set default-host x86_64-pc-windows-gnu gets the MinGW toolchain. Without a default host, pnpm installs the MSVC toolchain for the machine's architecture, as rustup does. This includes a pnpm built for MinGW, such as the MSYS2 package, which has installed the MinGW toolchain since 12.13.0. An x64 pnpm on ARM64 Windows now installs the ARM64 toolchain #16854.

Patch Changes#

Security#

• pnpm publish now uses an NPM_ID_TOKEN only if its aud claim matches the selected registry, such as npm:registry.npmjs.org. A token for another registry is skipped with a warning, and pnpm falls back to the configured credentials.

• The warning about renamed package files with invalid names no longer prints control characters from those file names.

Configuration#

• pnpm again accepts httpProxy and httpsProxy set to null or written with no value in pnpm-workspace.yaml and the global config file, and treats them as unset. Since 11.28.5 these values failed with ERR_PNPM_INVALID_SETTING.

• pnpm now switches to the pnpm version a project pins even when it cannot read its configuration. Previously, a setting it rejected in the global config file, an .npmrc file, _auth, or pnpm-workspace.yaml stopped every command, pnpm --version included.

• A key under a registry URL in the _auth setting that does not start with @ is now skipped with a warning, so a field a later pnpm version adds there no longer breaks this one. A key that holds an authToken object but lacks its @, such as org for @org, is still an error.

Resolving dependencies#

• pnpm no longer drops a dependency that a package also declares as an optional peer dependency, for example ajv of ajv-formats. Since 11.28.0, in some dependency graphs the package got the dependency neither as a dependency nor as a peer, and failed to import it #16901.

• pnpm install no longer fails with ERR_PNPM_NO_MATCHING_VERSION after a change to overrides when the lockfile resolves an optional peer dependency to an npm alias of another package #16654.

• pnpm install and pnpm dedupe now link an optional peer to the workspace package that the workspace root depends on when the picked version matches it. Previously they installed the registry package with the same name and version #16706.

• Removal overrides such as "debug>supports-color": "-" now also apply to an optional peer that a package declares only in peerDependenciesMeta #16681.

• pnpm dedupe now preserves a hoisted workspace package when another package uses a separately installed peer with the same name #16935.

• pnpm install and pnpm add --config now apply minimumReleaseAge when they resolve a config dependency. A config dependency range resolves to the newest version that is old enough, so a later clean pnpm install --frozen-lockfile accepts the lockfile #16660.

• pnpm install --fix-lockfile no longer removes the deprecated and hasBin fields from lockfile entries #6600.

Workspaces and catalogs#

• A filtered install, such as pnpm install --filter <pkg>, now keeps the pnpm-lock.yaml entries of workspace projects that are missing from disk, as in a sparse checkout. Their importers, packages, and catalog entries stay even when the filter matches every project on disk #16931.

• catalogPrune no longer removes catalog entries that pnpm-lock.yaml still records for workspace projects missing from disk. This affected pnpm remove and installs that leave the lockfile unchanged, such as frozen installs. Before, a following frozen install failed with ERR_PNPM_LOCKFILE_CONFIG_MISMATCH #16679.

• Sped up workspace discovery with subtree exclusions such as !generated/**.

Linking node_modules#

• pnpm install no longer fails on Windows with EPERM on rmdir node_modules/@scope when several workspace packages under one scope are hoisted, for example with nodeLinker: hoisted #16690.

• pnpm install hardlinks files from a group-writable or world-writable store again. Before this fix, pnpm copied every file from such a store into node_modules #16677.

• With enableGlobalVirtualStore, an install that updates node_modules now restores the dependency links of a package in the global virtual store that an interrupted install left without them. Before, such an install kept the incomplete package if the project's node_modules already recorded it #16642.

• Removing a link: dependency now also removes its symlink from node_modules when nodeLinker is hoisted #16884.

• An install that adds nothing to the store no longer changes the modification time of the store directory. CI caches that check modification times, such as GitLab's, no longer re-upload an unchanged store #16929.

Injected workspace packages#

• With sharedWorkspaceLockfile: false, an injected workspace package installed in the same run as its dependent now holds only the files its files field selects. The copy used to also hold other files of the project, such as tsconfig.json #16683.

• A script listed in syncInjectedDepsAfterScripts no longer fails when it rewrites package.json while pnpm is copying its edits into the injected copies. The sync after the script now replaces a half-copied manifest.

• Sped up frozen installs of unchanged injected workspace packages that use hardlinks.

Deploying#

• pnpm deploy without injectWorkspacePackages now binds a peer dependency of a linked workspace package to the version its parent provides, as an injected install does. Previously the deploy failed with ERR_PNPM_DEPLOY_AMBIGUOUS_PEER whenever other packages in the deployed graph depended on different versions of that peer #16807.

• pnpm deploy in a workspace with injectWorkspacePackages no longer crashes when a linked workspace package declares a peer dependency named after an Object.prototype member, such as constructor.

Setting up pnpm#

• pnpm now relinks the bins of a pnpm version it installed earlier for packageManager or pnpm with. A pnpm 12 version installed by a pnpm release older than 11.28.4 could keep a launcher that ran node on the native binary, so every command failed with SyntaxError: Invalid or unexpected token #16646.

• pnpm setup no longer tries to install pnpm globally from npm's bin directory when pnpm was installed with npm. It printed Failed to create bin at <PNPM_HOME>/bin/pnpm #16855.

Output#

• Escape codes in script output that moved the cursor or cleared the screen garbled pnpm's output. pnpm now drops them and keeps only color codes. Color codes are dropped too when pnpm's own output is not in color.

• When the registry rejects pnpm stage publish, the error message now starts with "Failed to stage package".

Minor Changes#

• Added the pnpm profile command to view and update registry user profile settings.

• Added pnpm token to list, create, and revoke authentication tokens on the registry.

• Added the storeIndexFormat setting. Set it to files to keep a store's package index as one file per package instead of the SQLite index.db, for a store on a network filesystem that several machines use at once. SQLite's locking does not work across machines, so concurrent installs on such a store could corrupt index.db.

• Added the nodePackageMap setting, which groups the package-map settings. nodePackageMap.mode: write-only writes node_modules/.package-map.json for other tools without making Node.js load it. mode: load also makes Node.js load the map, like nodeExperimentalPackageMap: true. nodePackageMap.type replaces nodePackageMapType. The old settings still work #14937.

  nodePackageMap:
    mode: write-only
    type: loose
  

Patch Changes#

Setting up pnpm#

• pnpm setup now works when pnpm was installed with npm on macOS. It installed pnpm from npm's bin directory and left a $PNPM_HOME/bin/pnpm that could not run #16855.

• pnpm runs again after pnpm setup when globalShims enables pnpm. Every command failed with "the global target of the pnpm shim points back at the shim" #16874.

• A pnpm built for the MinGW target on Windows, such as the MSYS2 package, now installs the MinGW Rust toolchain that rust-toolchain.toml names. It used to install the MSVC toolchain.

Installing packages#

• On macOS, pnpm install no longer fails with ERR_PNPM_LOCKFILE_WRITE_FILE when the project is on a virtiofs or SMB share. pnpm now falls back to a regular fsync when the file system rejects a full sync #16846.

• On macOS, pnpm install, pnpm patch-commit, and other commands that load a pnpmfile no longer hang at random.

• pnpm install now puts the executables of a Python build backend's requirements on the PATH while the backend runs. Projects built with uv_build now install. Before, they failed with "uv-build was not properly installed".

• Removing a link: dependency now also removes its symlink from node_modules when nodeLinker is hoisted #16884.

• pnpm-lock.yaml no longer records the tarball URL of a package installed from a scoped registry, such as one set by @types:registry=, when pnpm can rebuild the URL from that registry #16866.

Packing, auditing, and pipelines#

• pnpm pack and pnpm publish now pack only package.json, the README, the license, and the files named in main and bin when files is an empty array. They used to pack every file in the package #16889.

• pnpm audit and pnpm audit signatures no longer check runtimes installed through devEngines.runtime, such as node@runtime:24.21.0, against the npm package of the same name. pnpm audit signatures reported these runtimes as having an invalid registry signature #16869.

• pnpm pipeline now runs the root's tasks when pnpm-workspace.yaml lists only the root in packages or omits packages, as pnpm -r run does. A change to a root file in such a workspace no longer triggers a full-run warning. When a full run has no projects to run, pnpm pipeline now reports that no projects are selected #16849.

Performance#

• pnpm install resolves Python dependencies faster. With --lockfile-only, a project with 10 dependencies now resolves in about 4 seconds, down from about 40. When the index publishes a metadata file beside each wheel (PEP 658), as PyPI does, pnpm downloads only the wheels of the releases it selects.

• A repeat install against an existing lockfile no longer reads registry metadata for the dependencies it takes from that lockfile. On a warm store this removes thousands of metadata lookups from a repeat install of a large workspace.

• pnpm install with enableModulesDir: false now verifies the packages already in the store while the dependencies resolve, and checks a package's files in parallel. On a 5,100-package install with the store on a network filesystem, this removed a 19-second pause between resolution and fetching.

Patch Changes#

• pnpm publish now uses an NPM_ID_TOKEN only if its aud claim matches the selected registry, such as npm:registry.npmjs.org. A token for another registry is skipped with a warning, and pnpm falls back to the configured credentials.

• pnpm dist-tag add, rm, and ls now support OIDC authentication in CI. Enable "Allow npm dist-tag" in the package's trusted publishing settings to manage tags without a stored npm token.

• Added the tool: protocol for the tools pnpm downloads itself: Node.js, Bun, Deno, and Yarn. pnpm add bun@tool:1.3.0, pnx node@tool:22, and pnx yarn@tool:4 work like the runtime: spelling, which stays supported as an alias. A lockfile written for runtime: stays up to date when package.json switches to tool:, and the other way around.

  A named registry can no longer be called tool.

Minor Changes#

• pnpm pipeline can share task results between machines. A result is a signed artifact stored on a pnpr server or on a server that speaks the Turborepo Remote Cache API, such as Vercel Remote Cache.

  The remote side-effects cache can also store dependency builds on a Turborepo Remote Cache server. Both caches read the new remoteCache setting, which names the server and holds the signing keys. pnpm pipeline --report records the run under the organization remoteCache.org names.

• Added the addMissingPeerTypes setting, which links the @types package of a peer dependency next to every package that peer-depends on it. For example, a package that peer-depends on react gets the project's @types/react linked next to it. This lets TypeScript find the types of a peer dependency when the global virtual store is on #15689.

• pnpm add --config and pnpm update now handle configuration dependencies the way they handle other dependencies #16814.

  pnpm add --config saves a version range in pnpm-workspace.yaml by the same rules as pnpm add, so pnpm add --config my-config@latest saves a range such as ^1.2.0. It also resolves the package again when pnpm-lock.yaml already locks an older version.

  pnpm update updates configuration dependencies within their ranges, and pnpm update --latest moves them to their latest version. A selector such as pnpm update my-config updates only the configuration dependencies it names.

Patch Changes#

• A package set to false in allowBuilds no longer runs its build scripts when dangerouslyAllowAllBuilds is true. The two settings together now allow every build except the denied ones. Previously, dangerouslyAllowAllBuilds ignored the denials.

• pnpm now switches to the pnpm version a project pins even when it cannot read its configuration. Previously, a setting it rejected in the global config file, an .npmrc file, or _auth, or a pnpm-workspace.yaml it could not parse, stopped every command, pnpm --version included.

• pnpm update and pnpm why accept --depth Infinity again. They failed with invalid value 'Infinity' for '--depth <DEPTH>' #16817.

• pnpm deploy without injectWorkspacePackages now binds a peer dependency of a linked workspace package to the version its parent provides, as an injected install does. Previously the deploy failed with ERR_PNPM_DEPLOY_AMBIGUOUS_PEER whenever other packages in the deployed graph depended on different versions of that peer #16807.

• pnpm deploy --legacy no longer fails with ERR_PNPM_SPEC_NOT_SUPPORTED_BY_ANY_RESOLVER when a workspace dependency of the deployed project declares a workspace: peer dependency that the project does not depend on itself. pnpm now copies that peer from the workspace into the deploy directory.

  An auto-installed peer declared with workspace: now always resolves to the workspace project. Previously, workspace:* and workspace:^1.0.0 peers could be installed from the registry #16806.

• Repeat installs no longer resolve again when an injected workspace package lists a dependency also as a peer dependency.

• Sped up frozen installs of unchanged injected workspace packages that use hardlinks.

• Sped up workspace discovery with subtree exclusions such as !generated/**.

• A key under a registry URL in the _auth setting that does not start with @ is now skipped with a warning, so a field a later pnpm version adds there no longer breaks this one. A key that holds an authToken object but lacks its @, such as org for @org, is still an error.

Patch Changes#

• --workspace-concurrency=Infinity now runs workspace projects with no concurrency limit. It used to fail with invalid digit found in string #16793.

• pnpm install and other recursive commands now apply the filter and filterProd that an updateConfig hook sets. They used to run on every workspace project #16792.

• enable-modules-dir=false now also fetches the packages an install reuses from an existing lockfile, so the store holds every package the lockfile lists.

Patch Changes#

• pnpm install no longer fails when packageManager pins the pnpm version that is already running and the registry does not publish that version. pnpm warns and continues. A registry mirror that has not synced a release no longer blocks the commands of a project pinned to it.

• pnpm install no longer fails with ERR_PNPM_CMD_SHIM_CHMOD when node_modules/.bin holds a shim that another user created, if everyone can already execute it and it is not world-writable. This happens when several users share one checkout.

• enable-modules-dir=false (enableModulesDir: false through the Node.js addon) fetches the registry packages the host can install into the store again, as pnpm v10 did, while still writing nothing under node_modules. The setting exists for a node_modules that something else mounts from the store, such as a FUSE daemon, and that consumer no longer has to download each package on first access. A plain --lockfile-only run still fetches nothing.

• pnpm pack and pnpm publish no longer put .npmignore and .gitignore files in the tarball. A files entry that names one still ships it.

• pnpm now treats https://registry.npmjs.com/ as an alias of https://registry.npmjs.org/. Registry requests, credentials, and trusted publishing use the canonical hostname.

• pnx --package=rust@<channel> <tool> runs a tool of that Rust release, for example pnx --package=rust@nightly-2026-01-01 cargo build. pnpm installs the release with the components and targets from rust-toolchain.toml and the target of each --target argument.

• pnpm install now links agent skills for more coding agents. It detects the agent from ANTIGRAVITY_AGENT, COPILOT_AGENT, COPILOT_CLI, CODEX_THREAD_ID, CODEX_SANDBOX, AI_AGENT, and CLAUDE_CODE pnpm/tasks#116.

• When the registry rejects pnpm stage publish, the error message now starts with "Failed to stage package".

Minor Changes#

• pnpm install now links the agent skills that direct dependencies ship under skills/<name>/SKILL.md into the project's agent skill directories, such as .claude/skills. A package's skills are linked only after you approve them with pnpm approve. The skills.dirs setting chooses the directories pnpm/rfcs#35.

  Added the permissions setting, which records what each dependency may do. Its build capability works like allowBuilds and takes precedence over it. pnpm approve-builds writes to permissions when pnpm-workspace.yaml already has it, and to allowBuilds otherwise.

  Added pnpm permissions, which lists the granted and denied permissions and the packages awaiting approval. pnpm approve reviews build scripts and agent skills in one prompt pnpm/rfcs#36.

• pnpm now installs and runs Rust toolchains.

  • With cargo.enabled, pnpm install installs the toolchain named in rust-toolchain.toml. pnpm verifies the release signature, stores the toolchain once per machine, and links it into .pnpm/rust. pnpm run and pnpm exec put its cargo and rustc on the PATH.
  • pnpm add -g rust@<channel> installs a toolchain globally. The cargo and rustc commands run it outside projects that pin their own. pnpm update -g, pnpm ls -g, and pnpm remove -g manage it like any global package.
  • In a project, pnpm add rust@<channel> pins the toolchain in rust-toolchain.toml.
  • pnpm shim add rust adds project-aware shims for cargo, rustc, and the other Rust tools. In a project with a rust-toolchain.toml, they run the toolchain the file names and install it on first use. Elsewhere, the next command of the same name on PATH runs, such as rustup's.

• pnpm run and pnpm exec now keep the colors of script output that they print under the project's name, such as with --stream. pnpm sets FORCE_COLOR=1 for these scripts when its own output is in color, unless FORCE_COLOR is already set.

  Script output is also rendered more cleanly:

  • A line that a progress bar redraws with \r shows only its last state.
  • Escape codes that move the cursor or clear the screen are dropped.
  • Long colored lines are cut at the terminal width.
  • pnpm -r run no longer garbles its live output when a script fails while other scripts are still running.

Patch Changes#

Installing packages#

• pnpm no longer panics with "unexpected error when polling the I/O driver" when it runs under QEMU user-mode emulation, such as a linux/amd64 container on an Apple Silicon Mac #16696.

• pnpm view, pnpm update, and other commands that read registry metadata now work behind proxies that end a response by closing the connection without a TLS close_notify alert #16704.

• pnpm now switches to the version a project pins in packageManager or devEngines.packageManager even when pnpm-workspace.yaml has a setting the running pnpm cannot read, such as a lockfile.includeResolutionSettings section. If pnpm does not switch, it still reports that setting #16675.

• When the pnpm package has to download its native binary on first run, it now uses the registry and credentials from .npmrc and from the npm_config_registry and pnpm_config_registry environment variables. COREPACK_NPM_REGISTRY still takes precedence. A project .npmrc is not read when COREPACK_INTEGRITY_KEYS turns off the signature check #16655.

• pnpm install and pnpm add --config now apply minimumReleaseAge when they resolve a config dependency. A config dependency range resolves to the newest version that is old enough, so a later clean pnpm install --frozen-lockfile accepts the lockfile #16660.

• pnpm remove with catalogPrune no longer removes catalog entries that pnpm-lock.yaml still records for workspace projects missing from disk. Before, a following frozen install failed with ERR_PNPM_LOCKFILE_CONFIG_MISMATCH #16679.

• With cargo.enabled, pnpm install now writes the source replacement for vendored crates into .pnpm/crates/config.toml and includes it as optional from .cargo/config.toml. A checkout without .pnpm builds with plain Cargo #16659.

• With nodeLinker.type set to loaded, Node.js now stops with ERR_PNPM_LOADER_UNSUPPORTED_NODE when it preloads the store loader on a version the loader cannot serve. The supported versions are ^24.18.0 || >=26.2.0. On other versions, CommonJS packages imported from ESM failed with Cannot find module on their first relative require().

• On Windows, pnpm install no longer fails with "The filename, directory name, or volume label syntax is incorrect" when a package contains a file whose name is invalid on Windows, such as icon.svg?as=metadata.d.ts. pnpm removes the invalid characters from the name and prints a warning that lists the renamed files.

• On Windows, hoisting no longer fails intermittently with link errors when a junction is created or replaced concurrently pnpm/tasks#53.

Resolving dependencies#

• pnpm install --no-optional now installs the peer dependencies a project declares when autoInstallPeers is on. The lockfile marked such a peer optional: true when another dependency had it as an optional peer.

• pnpm install and pnpm dedupe now link an optional peer to the workspace package that the workspace root depends on when the picked version matches it. They installed the registry package with the same name and version #16706.

• Removal overrides such as "debug>supports-color": "-" now also apply to an optional peer that a package declares only in peerDependenciesMeta #16681.

• pnpm add and other installs that re-resolve dependencies now keep the locked devEngines.runtime version while it still satisfies the declared range #16764.

• pnpm audit --fix update now updates only the dependencies whose locked version is vulnerable #14928.

• pnpm outdated and pnpm update --interactive now apply overrides before they look up the latest version. Before, a dependency overridden to an npm alias was compared with the latest version of the package the override replaces #16719.

Patched dependencies#

• Patches saved with CRLF line endings now apply, including a patch that creates or deletes a file. pnpm rejected the git headers of such a patch with ERR_PNPM_INVALID_PATCH and the message invalid file mode: 100644 #16641.

• A patch that changes a file's mode, such as adding or removing the executable bit, now applies the new mode on Unix pnpm/tasks#110.

Injected dependencies and deploy#

• With sharedWorkspaceLockfile: false, an injected workspace package installed in the same run as its dependent now holds only the files its files field selects. The copy also held other files of the project, such as tsconfig.json #16683.

• A script listed in syncInjectedDepsAfterScripts no longer fails when it rewrites package.json while pnpm is copying its edits into the injected copies. The sync after the script now replaces a half-copied manifest.

• pnpm deploy with a shared lockfile no longer fails with ERR_PNPM_LOCKFILE_CONFIG_MISMATCH for settings.dedupeInjectedDeps or settings.dedupePeerDependents when lockfile.includeResolutionSettings is enabled. The deployed lockfile now records both settings as false, the values the deploy installs with.

• pnpm deploy now writes the dependencies in the deployed package.json sorted by name. It also sorts the allowBuilds entries in the deployed pnpm-workspace.yaml. Repeated deploys of the same lockfile now produce identical files #16687.

Packing and publishing#

• pnpm pack and pnpm publish now match .npmignore and .gitignore rules the way npm does. A negation such as !lib/** or !lib/**/!(*.map) re-includes files under a directory that an earlier * rule excluded #16743.

• pnpm pack and pnpm publish no longer always include root files that merely start with README, LICENSE, or LICENCE, such as README_INTERNAL.md. Only README, LICENSE, LICENCE, and COPYING, with or without an extension, ship regardless of files and .npmignore, as in npm #16753.

• pnpm publish --provenance=false and --no-provenance now turn off provenance under trusted publishing, so a package can be published from a self-hosted runner. Setting provenance: false in pnpm-workspace.yaml does the same #16721.

Speed and resource use#

• pnpm install hardlinks files from a group-writable or world-writable store again. pnpm copied every file from such a store into node_modules #16677.

• A repeat pnpm install no longer imports patched packages and packages with build scripts again when nothing changed. Their builds no longer run again either. This happened when recursiveInstall was false or the project had a file: dependency #16705.

• Verifying the lockfile against trustPolicy and minimumReleaseAge uses less memory. pnpm no longer keeps every published version's manifest of each checked package in memory until the install ends #16656.

• pnpm rebuild <pkg> and pnpm rebuild --pending no longer read the manifest of every installed package to find build scripts. Only the selected packages are inspected and built. On a large node_modules served lazily, such as over a network or FUSE mount, this turned a rebuild of a few packages into a fetch of every package.

• pnpm rebuild no longer removes and recreates node_modules when the settings recorded in node_modules/.modules.yaml differ from the current configuration. The rebuild runs the build scripts against the installed packages as they are.

• pnpm store prune now compacts the store's index.db after removing package entries, so the file shrinks again #16717.

Registry commands#

• pnpm whoami, pnpm bugs, pnpm docs, pnpm repo, pnpm star, pnpm unstar, and pnpm stars now honor the --registry option.

• --registry now takes precedence over a scope's configured registry for scoped packages in pnpm access, pnpm view, pnpm repo, pnpm star, pnpm unstar, pnpm owner, pnpm deprecate, pnpm undeprecate, pnpm unpublish, pnpm dist-tag, pnpm team, and pnpm stage. Without --registry, pnpm access now sends a scoped package or scope to the registry configured for that scope.

• Registry commands now keep the path of a registry URL such as https://example.com/npm/ when they build request URLs. This applies to pnpm access, pnpm owner, pnpm ping, pnpm search, pnpm star, pnpm stars, pnpm team, pnpm unstar, and pnpm whoami.

• pnpm view now honors the network retry settings.

• pnpm repo now fetches the repository URLs of several packages in parallel.

Patch Changes#

• With nodeLinker.type: loaded, pnpm now writes its generated files to node_modules, which projects already ignore in git. The store manifest and loader are node_modules/.pnpm/.store-manifest.json and node_modules/.pnpm/.store-loader.mjs. Bin shims are in node_modules/.bin.

  Earlier versions wrote .pnpm-store.json and .pnpm-store-loader.mjs to the project root, and a .pnpm directory to the root and to each workspace package. Delete them after reinstalling.

• With nodeLinker.type: loaded, packages that ship their own node_modules directory, such as npm with its bundled dependencies, now load from the store. Before, one such package in the install stopped every Node.js process from starting.

• With nodeLinker.type: loaded, scripts can now run a Node.js runtime installed through devEngines.runtime. Before, every script that called node re-ran its own shim until it failed with "Argument list too long".

• With nodeLinker.type: loaded, Node.js processes start faster. In a project with 13,000 stored files, the startup overhead per process dropped from 67 ms to 18 ms.

• pnpm install no longer fails with ERR_PNPM_NO_MATCHING_VERSION after a change to overrides when the lockfile resolves an optional peer dependency to an npm alias of another package #16654.

• A frozen install with catalogPrune no longer removes catalog entries that pnpm-lock.yaml still records. Before, pnpm install --frozen-lockfile --filter failed with ERR_PNPM_LOCKFILE_CONFIG_MISMATCH when some workspace projects were missing from disk #16638.

• pnpm install --fix-lockfile no longer removes the deprecated and hasBin fields from lockfile entries #6600.

• With enableGlobalVirtualStore, an install that updates node_modules now repairs a package in the global virtual store that an interrupted install left without some of its dependency links or package files. Before, such an install kept the incomplete package if the project's node_modules already recorded it #16642.

• pnpm install now skips the Cargo and Python projects inside a nested directory that has its own pnpm-workspace.yaml or .git directory, such as a git worktree of the same workspace or a separate clone.

• The Request took warning for package metadata now starts timing when pnpm sends the request. Before, it also counted the time the request waited for a free request slot, so large installs printed it for requests the registry answered quickly.

Minor Changes#

• Added experimental nodeLinker: { type: loaded } installation. Compatible dependencies load directly from the content-addressable store through an automatically registered Node.js loader. nodeLinker.excluded selects packages and their dependency trees to install in the global virtual store.

• lockfile.includeResolutionSettings: true makes pnpm-lock.yaml record autoDedupe, dedupeInjectedDeps, dedupePeerDependents and linkWorkspacePackages. Installs then treat a lockfile that records other values as outdated. A lockfile that records autoDedupe is reused by later installs on any machine, so pnpm run after pnpm install --frozen-lockfile no longer starts another install #16583.

Patch Changes#

Security#

• pnpm install now prevents dependency versions with path traversal from writing files outside the global virtual store.

• pnpm now verifies locked config dependencies against their registry before installing them. Config dependencies must come from an npm registry. The lockfile can no longer replace the integrity of a config dependency pinned with version+integrity.

• Lockfile verification now checks the tarballs inside a variations resolution against the registry. A name@version lockfile entry with an empty variations resolution is now rejected.

• pnpm audit signatures now verifies signatures against the integrity recorded in the lockfile. Packages without a recorded integrity cannot pass signature verification.

• pnpm install and pnpm publish now reject archive metadata larger than 64 MiB before reading it into memory. Publishing a pre-built tarball also rejects manifests and README files larger than 64 MiB.

• Two URL or local path dependencies no longer share a virtual store directory when one URL has +, #, :, or ? where the other has /. Such dependencies, including git dependencies pinned with #, now get a hash suffix on their directory name.

• The warning about an ignored project .npmrc registry setting no longer prints the username and password of a URL-scoped key such as //user:password@registry.example.com/${PATH}/:_authToken.

Installing and resolving dependencies#

• pnpm install now fails with ERR_PNPM_UNSUPPORTED_PROTOCOL when a dependency uses a specifier with a protocol pnpm does not support, such as Yarn's patch:. On Windows, such a specifier failed with os error 123. On other platforms, pnpm linked it to a directory that does not exist. Reading a package.json that fails now names the file #16590.

• pnpm install now fails with ERR_PNPM_PACKAGE_MANIFEST_INVALID_ATTRIBUTE when a project declares a dependency whose specifier is not a string, such as "is-positive": 42. Before, the dependency was silently left out of the lockfile. A readPackage hook can still correct the specifier.

• Fixed pnpm install failing with ERR_PNPM_CMD_SHIM_RESOLVE_PATH when an executable's parent directory contains a dangling symlink.

• pnpm install --frozen-lockfile no longer fails with ERR_PNPM_RESOLUTION_SHAPE_MISMATCH when a name@version lockfile entry has a resolution served by a custom fetcher pnpm/tasks#108.

• pnpm install --fix-lockfile repairs a lockfile whose importer references a package that has no snapshot entry, as left by a badly merged lockfile. It failed with ERR_PNPM_LOCKFILE_MISSING_DEPENDENCY since 12.8.0 #16618.

• When a dependency moves an exact dependency of its own to an older version, a peer dependency that pnpm installed automatically now moves with it. Before, pnpm install and pnpm dedupe kept the newer locked version of the peer, so the lockfile held two copies of it, for example two copies of vue pnpm/tasks#61.

• pnpm dedupe now reads registry metadata for a dependency pinned to an exact version, as pnpm install does. If the registry metadata disagreed with the package's package.json, the lockfile it wrote depended on whether minimumReleaseAge was set #16615.

Speed and size#

• Dependency resolution reads cached registry metadata faster. The metadata cache moved to <cache-dir>/v12/, so the first install after upgrading downloads registry metadata again. A damaged cache entry is downloaded again, or reported as an error when --offline is set. pnpm cache prune also removes the metadata cache that older pnpm versions wrote under <cache-dir>/v11/ #13512.

• Package metadata requests no longer wait behind queued tarball downloads when maxSockets or a proxy limits the connections to a registry. Large installs resolve faster and print fewer Request took warnings.

• Sped up installs in large workspaces on macOS when the dependency links already exist. pnpm now keeps a link that already points at the right package without trying to create it first. Relinking the direct dependencies of 1,000 workspace projects took 45 ms, down from 116 ms pnpm/tasks#65.

• Commands in a project that pins a different pnpm version start about 13 ms faster on macOS. pnpm now runs the pinned version's binary directly, without the shell script in front of it pnpm/tasks#66.

• The pnpm binary is about 0.9 MB smaller, and the arm64 Linux binary is about 1 MB smaller still.

Running scripts and commands#

• pnpm run no longer prints [ELIFECYCLE] Command failed ... after Ctrl+C ends the script. pnpm still exits the way the script's shell did: on Windows with the shell's exit code (cmd reports -1073741510, PowerShell 1), on Unix by re-raising SIGINT #16579.

• pnpm run "/<regex>/" now accepts JavaScript regular expression syntax such as lookahead and lookbehind. A selector like "/^hello:(?!b).*$/" failed with ERR_PNPM_NO_SCRIPT #16604.

• pnpm run and pnpm exec now forward --config.* command-line flags to the install started by verifyDepsBeforeRun pnpm/tasks#60.

• On Windows, a process started by pnpm run or pnpm exec can again start a child with CREATE_BREAKAWAY_FROM_JOB. That child keeps running after pnpm exits, even if the command fails #16628.

• Empty nodeOptions values from command-line flags and environment variables now override lower-priority settings. Scripts retain NODE_OPTIONS from the parent environment or extraEnv when nodeOptions is empty.

• pnpm now reads the failIfNoMatch setting from pnpm-workspace.yaml, so a filter that matches no workspace project exits with code 1 when the setting is true. The new --no-fail-if-no-match flag turns the setting off for one command #16577.

Configuration, setup, and pnpm versions#

• pnpm config get --global and pnpm config list --global now show only the global configuration, also when run inside a project. Settings from the project's pnpm-workspace.yaml and .npmrc were included before. The same applies to --location=global #16598.

• pnpm now prints config warnings, such as an unset environment variable in .npmrc, when loading the config fails.

• pnpm 11 releases older than 11.28.4 can run pnpm 12 again when the packageManager field pins it. Since 12.9.0 they failed with SyntaxError: Invalid or unexpected token #16594.

• On Windows, pnpm self-update no longer runs the update a second time when it replaces a pnpm.cmd linked by pnpm 12.8 or older. cmd.exe read on in the replaced pnpm.cmd, printed an error about a command that is not recognized, and ran the new pnpm once more #16573.

• pnpm setup now puts $PNPM_HOME/bin first on PATH in login shells that inherited it further down, such as the VS Code terminal on macOS. Before, another node took precedence over the one installed by pnpm runtime set node -g. Run pnpm setup again to update the block in your shell config #16635.

• pnpm setup now names the shell config file even if it is already up to date #16608.

Updating, auditing, and publishing#

• pnpm update --latest now applies the savePrefix setting when it rewrites a dependency whose range has no operator of its own, such as <2.0.0.

• The interactive pnpm audit --fix picker now shows each patched version with the saveExact and savePrefix style that the override is written with #13209.

• pnpm unpublish <pkg>@<version> now deletes the tarball under the registry's path when the registry is served under one, such as Gitea's npm registry. It used to send the delete to the host root and report success without removing the version #16568. It also no longer mistakes a sibling path such as /npm-mirror/ for the registry path /npm/ pnpm/tasks#94.

Output and messages#

• A warning about a project's devEngines or packageManager pin is now printed to stderr. A command such as pnpm cache path or pnpm list --json keeps only its own output on stdout #16584.

• pnpm list now reports the correct package paths when nodeLinker is hoisted #9593.

• Resolution errors now name the failing dependency and its parent packages. Fatal errors appear as structured error records with their error codes when using --reporter=ndjson.

• The error for an invalid git repository in the lockfile now has the code ERR_PNPM_INVALID_GIT_REPOSITORY. Its message now lists every rejected form of the value.

• pnpm runtime --help and pnpm help runtime now name the set subcommand and the runtimes it accepts #16580.

Patch Changes#

Security#

• pnpm now verifies locked config dependencies against their registry before installing them. Config dependencies must come from an npm registry. The lockfile can no longer replace the integrity of a config dependency pinned with version+integrity.

• Lockfile verification now checks the tarballs inside a variations resolution against the registry. A name@version lockfile entry with an empty variations resolution is now rejected.

• pnpm audit signatures now verifies signatures against the integrity recorded in the lockfile. Packages without a recorded integrity cannot pass signature verification.

• pnpm now rejects a git dependency whose lockfile repository is empty, begins with -, or contains a null byte. Git can no longer read such a value as a command-line option pnpm/tasks#84.

• A git dependency with a #path: subpath can no longer reach files outside the repository through a symlink in the subpath.

• pnpm pack, pnpm publish, and installs of git and local directory dependencies now leave out files that a directory symlink or a bundleDependencies entry points to outside the package directory pnpm/tasks#83 pnpm/tasks#93.

• pnpm deploy with deployAllFiles now rejects symlinks that point outside the package directory. Local package installs with this setting apply the same check.

• pnpm no longer hangs on a package archive with a negative PAX record length or an entry of 4 GiB or more pnpm/tasks#78 pnpm/tasks#79.

• Large package downloads and large files inside gzip and bzip2 package archives now use bounded memory during installation. Package manifests and archive metadata larger than 64 MiB are rejected. pnpm publish also rejects manifests and README files larger than 64 MiB in pre-built tarballs before reading them into memory.

• Two URL or local path dependencies no longer share a virtual store directory when one URL has +, #, :, or ? where the other has /. Such dependencies, including git dependencies pinned with #, now get a hash suffix on their directory name.

• pnpm licenses now removes terminal control characters from package metadata in table output.

• The warnings about ignored project .npmrc registry and auth settings no longer print the username and password of a URL-scoped key such as //user:password@registry.example.com/:_authToken.

Installing and resolving dependencies#

• Dependency resolution reads cached registry metadata faster. The metadata cache moved to <cache-dir>/v12/, so the first install after upgrading downloads registry metadata again. A damaged cache entry is downloaded again, or reported as an error when --offline is set #13512.

• pnpm install now fails with ERR_PNPM_UNSUPPORTED_PROTOCOL when a dependency uses a specifier with a protocol pnpm does not support, such as Yarn's patch:. pnpm linked such a dependency to a directory that does not exist #16590.

• When a dependency moves an exact dependency of its own to an older version, a peer dependency that pnpm installed automatically now moves with it. Before, pnpm install and pnpm dedupe kept the newer locked version of the peer, so the lockfile held two copies of it, for example two copies of vue pnpm/tasks#61.

• pnpm add and pnpm install now keep the peer dependencies that pnpm-lock.yaml records for a package they did not update. A registry whose metadata disagrees with the package's package.json, for example by omitting peerDependenciesMeta, made pnpm add and pnpm dedupe write different lockfiles, so pnpm dedupe --check failed after pnpm add #16615.

Configuration#

• pnpm config get and pnpm config list with --global or --location=global now show only the global configuration. Both flags included the project's .npmrc before. --location=global also included the project's pnpm-workspace.yaml. pnpm config get --global failed when the global bin directory was not in PATH #16598.

• pnpm now prints config warnings, such as an unset environment variable in .npmrc, when loading the config fails.

• pnpm now fails when httpProxy or httpsProxy in pnpm-workspace.yaml or the global configuration is not a string.

• pnpm dlx now uses the release entry of nodeDownloadMirrors from the workspace configuration when downloading Node.js runtimes #11281. Mirrors for other channels, such as rc and nightly, still apply only from the global configuration.

Commands#

• pnpm run and pnpm exec now forward --config.* command-line flags to the install started by verifyDepsBeforeRun pnpm/tasks#60.

• pnpm dlx with --package but no command now fails with 'pnpm dlx' requires a command to run. Before, it installed the package and then crashed trying to run an empty command.

• pnpm unpublish <pkg>@<version> now deletes the tarball under the registry's path when the registry is served under one, such as Gitea's npm registry. It used to send the delete to the host root and report success without removing the version #16568. It also no longer mistakes a sibling path such as /npm-mirror/ for the registry path /npm/ pnpm/tasks#94.

• The interactive pnpm audit --fix picker now shows each patched version with the saveExact and savePrefix style that the override is written with #13209.

• pnpm list now reports the correct package paths when nodeLinker is hoisted #9593.

• pnpm setup now puts $PNPM_HOME/bin first on PATH in login shells that inherited it further down, such as the VS Code terminal on macOS. Before, another node took precedence over the one installed by pnpm runtime set node -g. Run pnpm setup again to update the block in your shell config #16635.

• pnpm setup now names the shell config file even if it is already up to date #16608.

Output and messages#

• A warning about a project's devEngines or packageManager pin is now printed to stderr. A command such as pnpm cache path or pnpm list --json keeps only its own output on stdout #16584.

• The warning for a non-root resolutions field now points at the overrides field in pnpm-workspace.yaml #11757.

Patch Changes#

• The WebAssembly build for StackBlitz WebContainers now ships as a separate @pnpm/wasm package. The pnpm and @pnpm/exe packages no longer include it, which brings their unpacked size back from about 55 MB to about 4 MB. In a WebContainer, install @pnpm/wasm with npm to get the pnpm command.

• pnpm publish with provenance from GitLab CI is no longer rejected by the npm registry with a 422 error. The provenance statement now includes the GitLab CI variables in invocation.parameters, as npm does #16551.

• pnpm audit signatures now uses the TLS settings of the redirect target when a registry redirects its signing-keys request, for example to registry.npmjs.org. A cafile scoped to a private registry no longer makes the redirected request fail #16541.

• Fixed pnpm install --frozen-lockfile rejecting an up-to-date lockfile when an injected workspace package uses a catalog entry in peerDependencies #16557.

• The [<since>] filter selector works again with Git 2.24 through 2.27 #16561. With Git older than 2.24, the selector now fails with an error that names the required Git version.

  It also detects changes in projects whose directory names contain non-ASCII characters. Such a change used to be credited to the parent project. changedFilesIgnorePattern and testPattern now match changed files whose names contain non-ASCII characters.

• The pnpm executable is about 10% smaller. On macOS arm64 it went from 45.1 MB to 40.3 MB.

• Sped up trust downgrade checks for packages with long release histories.

• With optimisticRepeatInstall: false, pnpm install now runs the projects' own lifecycle scripts, such as prepare, even when node_modules is already up to date #16545.

• pnpm self-update now fails for Homebrew-installed pnpm and prints the brew upgrade command for the installed formula, such as brew upgrade pnpm or brew upgrade pnpm@11. It used to install a second copy of pnpm that the Homebrew one kept shadowing #16547.

Patch Changes#

• pnpm login no longer forwards credentials in its request body to another origin during redirects.

• The error for a tarball that fails its integrity check no longer prints credentials, query strings, or fragments from the tarball URL.

Installing packages#

• pnpm install --frozen-lockfile now succeeds in a project with no dependencies when pnpm-lock.yaml records only the pinned pnpm version. Other commands write such a lockfile when they run before the first install. A lockfile missing the --- line after that section is accepted too #16477.

• pnpm install --frozen-lockfile again succeeds when a workspace project recorded in pnpm-lock.yaml has no directory, such as a project left out of a Docker build context. It still fails if the project's directory exists without a package.json #16453.

• pnpm install --frozen-lockfile no longer fails with ERR_PNPM_OUTDATED_LOCKFILE for a workspace project that declares dependenciesMeta and whose dependencies are all workspace links. pnpm now records that project's dependenciesMeta in pnpm-lock.yaml #16457.

• Fixed frozen installs replacing a hoisted dependency with a workspace package of the same name. A later pnpm dedupe then removed the hoisted link #16485.

• With enableGlobalVirtualStore on, scripts can run entry points that a CommonJS require hook loads again, such as ts-node index.ts. They failed with ERR_UNKNOWN_FILE_EXTENSION on Node.js versions without built-in TypeScript support #16436.

Optional dependencies#

• pnpm install now prints a warning with the error when an optional dependency cannot be fetched and is skipped. The skipped package is no longer linked into node_modules as a broken symlink or listed among the added dependencies. The pnpm:skipped-optional-dependency log reports the skip with the fetch_failure reason #16514.

• When an optional dependency fails to build, pnpm now removes its link from node_modules. A repeat pnpm install then reports "Already up to date" and no longer reruns the failing build #16468.

• Fixed frozen installs creating symlinks to the working directory for skipped optional dependencies and unresolved peer dependencies #16454.

Hoisted node_modules#

• With nodeLinker: hoisted, a filtered install now keeps the packages of the workspace projects an earlier install put in node_modules. This also covers the install that pnpm --filter <selector> run and pnpm --filter <selector> exec start before the command. Before, these installs removed every package that only the unselected projects needed #16483.

  A filtered install of a workspace project also no longer fails with ERR_PNPM_LOCKFILE_MISSING_DEPENDENCY after a filtered install of another project.

• pnpm install with nodeLinker: hoisted now refreshes directories supplied by custom fetchers when reinstalling.

Speed and network#

• pnpm now revalidates cached registry metadata with a conditional request, so the registry can answer 304 Not Modified. Before, pnpm downloaded the whole document again for registries whose responses forbid caching, such as Cache-Control: no-store #16528, and for packages published within minimumReleaseAge #16506.

• A fetch timeout while other downloads from the same host are still running now lowers concurrency for that host to one connection. Retries of that request, and later downloads from that host, use the lower concurrency. Other hosts keep the configured concurrency #12791.

Running scripts#

• Scripts run without a terminal no longer start a second sh each. One watchdog per pnpm command now ends every script's process group if pnpm is killed, so pnpm -r run across many projects starts half as many processes #16489.

• pnpm run and pnpm exec now warn and run the command when the install that verifyDepsBeforeRun starts fails. This lets scripts run in sandboxes where pnpm cannot install, such as containers with a read-only store or no network #15173.

• A filtered pnpm run or pnpm exec now finds dependencies out of date when a workspace dependency of a selected project has no node_modules directory, as after a filtered install. With verifyDepsBeforeRun: install, pnpm installs that dependency before running the command pnpm/tasks#45.

• pnpm rebuild and pnpm approve-builds refresh command launchers when a build changes a command's interpreter or replaces it with a native executable. Dependent packages' build scripts use the refreshed launchers.

Updating pnpm#

• pnpm self-update now fails for Homebrew-installed pnpm and prints the brew upgrade command for the installed formula, such as brew upgrade pnpm or brew upgrade pnpm@11. It used to install a second copy of pnpm that the Homebrew one kept shadowing #16547.

• On Windows, pnpm self-update now replaces a pnpm.exe left in PNPM_HOME or in PNPM_HOME\bin. In PNPM_HOME, that executable kept running the old version after a successful update. In PNPM_HOME\bin, the update failed with EPERM. If the executable was in PNPM_HOME, self-update now asks you to run pnpm setup #9094.

• pnpm can now switch to a packageManager version below 11 on x64 musl Linux, such as Alpine #16467.

• A devEngines.packageManager range now records the running pnpm in pnpm-lock.yaml only if it meets minimumReleaseAge. Otherwise pnpm records the newest version in the range that meets it. If no version in the range does, pnpm still records the running pnpm #16431.

Filtering, settings, and other commands#

• The [<since>] filter selector works again with Git 2.24 through 2.27 #16561. With Git older than 2.24, the selector now fails with an error that names the required Git version.

• Package-name filters now support ? to match one character #2817.

• pnpm -r pkg get now reports every selected project when several share a package name. Projects with the same name are keyed by their directory relative to the workspace root. Before, only one of them appeared in the output.

• pnpm now reports an INVALID_SETTING error when allowUnusedPatches in pnpm-workspace.yaml is not a boolean, or when ignoredOptionalDependencies or requiredScripts is not an array of strings. A quoted allowUnusedPatches value such as "false" was treated as true.

• pnpm store path, pnpm store status, and other commands that look up the default store no longer fail when the current directory is not writable. pnpm now uses the store in the pnpm home directory in that case #16554.

Minor Changes#

• pnpm now automatically uses WebAssembly in StackBlitz WebContainers, including when installation scripts are disabled. Native installations continue to use the native executable when installation scripts are enabled.

• A registries entry can now set networkConcurrency, the most requests pnpm keeps in flight to that registry's origin. Requests to other registries keep the overall limit. The setting may live in pnpm-workspace.yaml or the global config.yaml.

  registries:
    https://npm.corp.example.com/:
      scopes: ["@acme"]
      networkConcurrency: 4
  

• pnpm install now records every project it installs in the store's projects directory, as a symlink to the project directory. A --frozen-store install without the global virtual store still records nothing. Only projects that used the global virtual store were recorded before #6929.

Patch Changes#

• pnpm login no longer forwards credentials in its request body to another origin during redirects.

Installing packages#

• Fixed pnpm install failing on Android with ERR_PNPM_STORE_DIR_ACQUIRE_OPERATION_LOCK #16508.

• pnpm install --frozen-lockfile again succeeds when a workspace project recorded in pnpm-lock.yaml has no directory, such as a project left out of a Docker build context. It still fails if the project's directory exists without a package.json #16453.

• pnpm install --frozen-lockfile no longer requires a pnpm-lock.yaml in a project that has no dependencies. It also succeeds when pnpm-lock.yaml records only the pinned pnpm version, as other commands write it when they run before the first install #16477.

• Fixed pnpm install --frozen-lockfile rejecting a fresh lockfile when an injected workspace dependency has an optional peer supplied by another workspace project #16428.

• With nodeLinker: hoisted, a filtered install now keeps the packages of the workspace projects an earlier install put in node_modules. This also covers the install that pnpm --filter <selector> run and pnpm --filter <selector> exec start before the command. Before, these installs removed every package that only the unselected projects needed #16483.

• pnpm install with nodeLinker: hoisted now refreshes directories supplied by custom fetchers when reinstalling. pnpm also keeps the symlinks inside those directories.

• With enableGlobalVirtualStore on, scripts can run entry points that a CommonJS require hook loads again, such as ts-node index.ts. They failed with ERR_UNKNOWN_FILE_EXTENSION on Node.js versions without built-in TypeScript support #16436.

• pnpm now keeps each project's current lockfile and hidden hoisted dependencies in its own node_modules/.pnpm when virtualStoreDir points at a shared global virtual store. --virtual-store-dir now sets the global virtual store's location too pnpm/tasks#47.

• pnpm clean no longer deletes the project when virtualStoreDir or globalVirtualStoreDir is set to the project directory. It also leaves a directory outside the project alone when the setting reaches it through a symlink. It now removes a global virtual store that globalVirtualStoreDir places inside the project, as it does for virtualStoreDir.

Optional dependencies#

• pnpm install no longer fails when a dependency of an optional dependency is missing from the registry. Like npm, pnpm now leaves out the nearest optional dependency above it, together with its subtree #16511.

• When an optional dependency fails to build, pnpm now removes its link from node_modules. A repeat pnpm install then reports "Already up to date" and no longer reruns the failing build #16468.

• pnpm install now prints a warning with the error when an optional dependency cannot be fetched and is skipped. The skipped package is no longer counted in the Packages: +N summary. The pnpm:skipped-optional-dependency log reports the skip with the fetch_failure reason #16514.

Resolving dependencies#

• Fixed pnpm install changing an unchanged project's direct dependency to a sibling workspace's pinned version when its dependency tree contains a cycle #16417.

• With autoDedupe enabled, downgrading a dependency in one workspace project now moves the other projects to that version when it satisfies their ranges. This also applies to a filtered pnpm --filter <project> add #16432.

• pnpm install and pnpm dedupe now move an optional peer to the version already in the dependency graph when no other package provides its locked version anymore. After a bump such as vue 3.5.40 to 3.5.43, the lockfile kept a second copy of @vue/server-renderer for @vue/test-utils #16443.

• pnpm dedupe --check no longer fails right after pnpm install when a project's optional peer is satisfied by a package another workspace project installs. pnpm dedupe now picks the same versions for that package's dependencies as pnpm install #16447.

• pnpm install no longer re-resolves an up-to-date lockfile on every run when a patched package is a peer in a peer cycle #16418.

• With autoDedupe enabled, pnpm install --lockfile-only no longer resolves the dependency graph again when nothing changed since an earlier --lockfile-only install deduplicated the lockfile. Such an install keeps the lockfile even if versions were published since it was written, or if only a setting such as resolutionMode changed. Run pnpm dedupe to apply such a change #16458.

Speed and network#

• A repeat pnpm install in a large workspace reports "Already up to date" faster #16487.

• Sped up dependency resolution of workspaces with many peer dependencies.

• pnpm install sends fewer registry metadata requests when the lockfile already decides which version a range resolves to. This now also covers ranges that several locked versions satisfy when one of them outranks the others, and direct dependencies kept at their locked version. Packages that minimumReleaseAgeExclude lists without a version now reuse cached registry metadata the same way they do when minimumReleaseAge is not set #16458.

• pnpm no longer downloads every packument again on each install from a registry whose metadata responses forbid caching, such as Cache-Control: no-store. pnpm revalidates the cached metadata with a conditional request, so a registry that supports conditional requests answers with a 304 when the package has not changed #16528.

• Cached metadata for a package published within minimumReleaseAge is now revalidated with its ETag, so the npm registry can answer 304 Not Modified. Before, the next install that checked the cache downloaded the whole document again #16506.

• A fetch timeout while other downloads from the same host are still running now lowers concurrency for that host to one connection. Retries of that request, and later downloads from that host, use the lower concurrency. Other hosts keep the configured concurrency #12791.

• Sped up pnpm install --offline when the version a range picks is not in the store. While it looks for a version the store holds, pnpm now reads only the versions the range admits #16495.

• pnpm install --offline now reuses config dependency tarballs that are already present in the store pnpm/tasks#46.

Running scripts#

• pnpm -s <script> runs the script again, with -s meaning --sequential as it does for pnpm run -s <script>. pnpm rejected it with "unexpected argument '-s' found" #16446.

• pnpm run and pnpm exec now warn and run the command when the install that verifyDepsBeforeRun starts fails. This lets scripts run in sandboxes where pnpm cannot install, such as containers with a read-only store or no network #15173.

• A filtered pnpm run or pnpm exec now finds dependencies out of date when a workspace dependency of a selected project has no node_modules directory, as after a filtered install. With verifyDepsBeforeRun: install, pnpm installs that dependency before running the command pnpm/tasks#45.

• Scripts run without a terminal no longer start a second sh each. One watchdog per pnpm command now ends every script's process group if pnpm is killed, so pnpm -r run across many projects starts half as many processes #16489.

• Terminate batch job (Y/N)? no longer appears after pressing Ctrl+C in a script started with pnpm from PowerShell or cmd on Windows #16502.

• pnpm rebuild and pnpm approve-builds refresh command launchers when a build changes a command's interpreter or replaces it with a native executable. Dependent packages' build scripts use the refreshed launchers.

• When pnpm run <script> or pnpm <script> finds nothing to run and --filter follows the script name, the error now suggests putting the filter option before the script name #4655.

• Package-name filters now support ? to match one character #2817.

The pinned pnpm and pnpm self-update#

• pnpm no longer downloads the project's pinned pnpm version again on every command when nodeVersion in pnpm-workspace.yaml names a different Node.js major than the node on PATH. Before, each of those commands took about a second longer and failed without network access #16497.

• Several pnpm commands started at once in a project that pins packageManager no longer fail with The process cannot access the file because it is being used by another process on Windows while the pinned pnpm is being installed.

• pnpm can now switch to a packageManager version below 11 on x64 musl Linux, such as Alpine #16467.

• A devEngines.packageManager range no longer makes pnpm replace the version recorded in pnpm-lock.yaml with the running pnpm while the recorded version still satisfies the range. When pnpm does record a version, it records the running pnpm only if it meets minimumReleaseAge. Otherwise it records the newest version in the range that meets it, or the running pnpm if none does #16431.

• On Windows, pnpm self-update now replaces a pnpm.exe left in PNPM_HOME or in PNPM_HOME\bin. Windows ran that executable in place of the updated pnpm.cmd shim, so pnpm --version kept printing the old version after a successful update. If the executable was in PNPM_HOME, self-update now asks you to run pnpm setup #9094.

• pnpm self-update now checks that a version installed as the JavaScript pnpm can start before making it the global pnpm. If Node.js is missing, the update fails and the current pnpm stays in place.

Other commands#

• pnpm deploy now finds patches and local dependencies when the target directory sits under a symlink, such as /tmp on macOS. It failed with ERR_PNPM_PATCH_NOT_FOUND #16470.

• pnpm deploy --legacy now resolves the deployed project's relative file:, link:, and path dependencies from the project's own directory #16475.

• pnpm update --global now removes hard-linked executables from PNPM_HOME when migrating packages from the old global layout #16420.

• pnpm store prune no longer fails on store index entries that pnpm 11 wrote for git-hosted packages without a package.json. Entries that still cannot be read are kept and counted in the prune summary.

• pnpm store prune now aborts when an error other than a missing directory occurs while scanning project directories in the mark phase.

• pnpm config get and pnpm config list now report a setting given on the command line with --config.<name>=<value>. Before, a value such as --config.node-linker=hoisted reached the install but was absent from the reported configuration #16276.

• pnpm -r pkg get now reports every selected project when several share a package name. Projects with the same name are keyed by their directory relative to the workspace root. Before, only one of them appeared in the output.

• The install summary shows a link: dependency as + name <- path, and the Node.js API's hideLinkedPkgsDiff reporter option leaves matching linked dependencies out of the summary.

• The --force help text of pnpm install and pnpm add now says that --force keeps skipping optional dependencies built for other platforms. It points to forceIgnoresPlatform and the --os, --cpu, and --libc options for installing them #16435.

• The homepage field of the published pnpm package points to https://pnpm.io again.

Patch Changes#

Platforms and environments#

• Fixed pnpm crashing on startup on Linux ppc64le #16380.

• Fixed installs failing with UnknownIssuer on Linux systems without CA certificates, such as node:24-slim, when NODE_EXTRA_CA_CERTS is set. The extra certificates now extend the bundled CA roots #16365.

• pnpm now creates its store operation locks and other per-user lock files in $XDG_RUNTIME_DIR when it points to a directory only the user can write to. Otherwise, pnpm still uses /tmp on Linux and macOS. Sandboxes that block writes to /tmp can point XDG_RUNTIME_DIR at a writable directory #16390.

• POSIX bin shims and the pnpm, pn, pnpx, and pnx launchers now run inside a Nix build, where the system default path holds none of the utilities they call. Installing again replaces the shims already in node_modules #16377.

• In a project that pins another pnpm version, pnpm now passes a command with an option it does not know to the pinned version. Before, pnpm rejected the option before switching, so pnpm install --auto-dedupe failed with "Unknown option" even though the pinned pnpm supports it #16353.

Installing and resolving dependencies#

• pnpm install --frozen-lockfile now fails when Cargo.lock does not satisfy a dependency requirement in Cargo.toml. The error names the crate and the version the lockfile holds #16355.

• pnpm install returns "Already up to date" again in a workspace with injected workspace dependencies and a shared lockfile. Since 12.7.0 every repeat install in such a workspace ran the full install and copied the injected projects again.

• With injectWorkspacePackages: true, a fresh pnpm install now records a workspace dependency as link: when its injected copy differs from the project only by an optional peer that peer-dependent dedupe merges. It was recorded as a peer-suffixed file: copy #16354.

• pnpm dedupe --check now passes right after pnpm dedupe when deduplication merges variants of a package that differ only in their peers. A lockfile key whose peer suffix named a merged variant now names the variant that replaced it #16356.

• When minimumReleaseAge hides the version that latest points to, pnpm now falls back to a prerelease of the same major before a stable version of an older major. A stable version of the same major is still preferred. Before, while a new 1.0.0 was too new, latest fell back to an old 0.0.1 even though 1.0.0-beta.4 had been latest until then #16388.

• Git-hosted dependencies now respect pmOnFail. If it is set to anything other than download, a git-hosted dependency that pins a pnpm version is prepared by the running pnpm, and pnpm does not download the pinned version #16376.

• pnpmfile hooks such as readPackage now run once for a dependency that several packages request at the same time. They could run twice for it before.

• childConcurrency now defaults to 5, the documented value. It used to be capped at 4 and to follow the host's CPU count.

Running scripts#

• pnpm run and pnpm exec no longer install dependencies before every script on CI when autoDedupe is enabled. pnpm install --frozen-lockfile now keeps the deduplication record left by an earlier install #16374.

• On macOS and Linux, lifecycle scripts and pnpm run now always get PATH from the PATH variable. When the environment also held a Path variable, a script sometimes got Path's value, and failed with node: not found #16308.

• pnpm run now exits after a SIGTERM in a container where pnpm is PID 1 and the script runs pnpm again, as "start": "pnpm serve" does. Since 12.6.0 it kept waiting after the script had shut down, until the container runtime killed it.

Other commands and settings#

• pnpm config get globalShims, pnpm shim list, and global installs no longer read globalShims from a project's pnpm-workspace.yaml. Only the global config file, the pnpm home's own pnpm-workspace.yaml, and PNPM_CONFIG_GLOBAL_SHIMS set it, so a repository cannot choose which globally installed packages get project-aware shims.

• pnpm config set --location=project refuses a machine-level setting such as stateDir or scope with ERR_PNPM_CONFIG_SET_NOT_A_PROJECT_SETTING, which names where the setting belongs. pnpm config delete still clears such a key from a project's pnpm-workspace.yaml.

• pnpm deploy no longer fails with ERR_PNPM_DEPLOY_AMBIGUOUS_PEER in a workspace with injectWorkspacePackages: true when a workspace package lists its peer dependency as a dev dependency too #16375.

• pnpm deploy no longer copies the workspace root's packageManager and devEngines.packageManager fields into the deployed package.json #16403.

• pnpm publish now includes bare README files and README files with Markdown extensions such as readme.markdown in registry metadata #12704.

• pnpm store prune now removes the packages that only expired pnpm dlx cache entries used. They were left in the store until the next pnpm store prune #16383.

Performance#

• Sped up dependency resolution in large workspaces, and when many dependencies request different ranges of the same package. Resolution also uses less memory.

• Sped up pnpm install with nodeLinker: hoisted on macOS when the lockfile is re-resolved, such as with autoDedupe enabled #16397.

• Sped up extracting package tarballs.

• pnpm install without --frozen-lockfile is faster on some machines in projects with a pnpm-workspace.yaml. Those installs linked with one worker thread per core, half of what a frozen install uses.

• On Windows, warm pnpm install --frozen-lockfile runs are 4-5% faster on 4- and 8-core machines. pnpm now links with one worker thread per core on Windows, between 4 and 16. This changes frozen installs and installs in projects without a pnpm-workspace.yaml on machines with 3 to 15 cores.

Minor Changes#

Warning about .env files in packages#

pnpm pack and pnpm publish now warn when the tarball includes a .env or .env.* file that the files field of package.json does not list (#7826). Templates such as .env.example are not reported. List the file in files to publish it on purpose, or exclude it in .npmignore or .gitignore.

Concurrent installs without a shared lockfile#

In a workspace with sharedWorkspaceLockfile: false, pnpm install now installs projects concurrently, up to workspaceConcurrency at a time (#14480). A project is resolved, fetched, and written to its virtual store without waiting for the workspace projects it depends on. It waits for them only before it links its dependencies and runs its lifecycle scripts, so its scripts still run after theirs. A project with a preinstall or pnpm:devPreinstall script, or with an injected or file: workspace dependency, waits for its workspace dependencies before it starts.

The installs also share package metadata, lockfile verification, and store caches, so they use less CPU and memory when several projects depend on the same packages.

Related fixes for such workspaces:

• With enableGlobalVirtualStore, each project keeps its current lockfile and its hidden hoisted dependencies in its own node_modules/.pnpm, so a repeat install no longer relinks the other projects' packages.
• pnpm rebuild, pnpm approve-builds, and pnpm ignored-builds work on the current project's node_modules (#9402).
• An injected workspace package that has lifecycle scripts is hard linked into the projects that depend on it, so later edits reach them (#9828).

Every setting accepted as --config.<name>#

Every setting pnpm supports can now be set with --config.<name>=<value> on the command line, not only the ones whose command also carries a matching flag (#16276). Before, pnpm install --config.frozen-lockfile=true dropped the setting and rewrote pnpm-lock.yaml as though the install had not been frozen.

Settings given on the command line, such as --registry and --store-dir, now also take precedence over the values a pnpmfile updateConfig hook sets (#14063).

Ctrl+C on Windows#

Interrupting a script with Ctrl+C on Windows no longer leaves the terminal stuck (#14860). A script that runs through a batch shim, as vite dev does through vite.CMD, made cmd.exe wait forever on its "Terminate batch job (Y/N)?" answer, and every following keystroke went to that prompt. pnpm now ends a cmd.exe script shell once it has sat for a second after the interrupt with nothing running under it. A script that takes longer to shut down is still waited for, and a second Ctrl+C ends the script's shell at once.

Other changes#

• pnpm pack honors --silent, --reporter=silent, and --loglevel=silent to hide the tarball contents and summary (#10297).
• An in-place edit to the source of an injected workspace package now shows up in its injected copy, unless a build writes to that package or packageImportMethod is set (#4410). Scripts listed in syncInjectedDepsAfterScripts now update injected dependencies while they run, so a dev server watching the injected package sees each change before the script exits.
• pnpm update --global reinstalls the global packages that pnpm 10 installed into <global-dir>/5, so their commands are linked again and pnpm list --global lists them. Once every package is migrated, pnpm deletes the previous directory (#11528).
• pnpm install runs the install hooks of a config dependency plugin's pnpmfile, including readPackage, afterAllResolved, and custom resolvers. Before, only its updateConfig hook ran.
• Scripts see the npm_command environment variable (#16265) and an npm_config_node_gyp that points at the bundled node-gyp (#16270).

Patch Changes#

Installing#

• pnpm install --dev and pnpm fetch --dev install the optional dependencies of devDependencies, such as the platform binaries of Biome and oxlint (#9678).
• pnpm install --offline and pnpm add --offline resolve a range to the newest matching version whose tarball is already in the store (#10715).
• An offline install that fails on a metadata cache from before pnpm 12.4 explains that one online install repopulates it, with the ERR_PNPM_NO_OFFLINE_META code (#15656).
• Installing a git-hosted dependency that has to be built no longer fails on unapproved build scripts of its own dependencies (#9764), and a git-hosted pnpm workspace without a committed lockfile is detected as a pnpm project (#14011).
• pnpm install refreshes dependencies when a local file: directory changes its dependencies (#4623).
• An optional dependency whose install script fails is removed from node_modules (#8756).
• With nodeLinker: hoisted, pnpm install restores a deleted workspace project's node_modules, and clears orphaned package directories that an interrupted install left behind (#13676).
• Installing through a pnpr server records the pnpmfile checksum in the lockfile (#14460) and links a workspace project at its publishConfig.directory.

Resolving and linking#

• pnpm install no longer aborts on a huge allocation when peer ranges combine overlapping || alternatives (#15867).
• A registry package with a file: dependency on a directory inside itself, such as "@types/css-tree": "file:./typings/css-tree", installs as it does with npm and Yarn (#9141).
• An npm: alias written by overrides stays in place when pnpm re-resolves the aliased dependency (#16309).
• A peer dependency no longer resolves to two different versions for one package (#12098), and an optional peer is no longer resolved from another workspace project's package when that causes bogus unmet peer errors (#13989).
• pnpm dedupe no longer changes the lockfile on every run when a nested peer is provided through an npm alias (#15709).
• With resolutionMode: time-based and minimumReleaseAge both set, a subdependency is no longer reported as too new when only the time-based cutoff excludes it (#13569, #16298).
• A transient metadata fetch failure is retried and no longer reported as TRUST_DOWNGRADE or MINIMUM_RELEASE_AGE_VIOLATION (#12031).
• pnpm's built-in package compatibility database no longer applies to a project's own manifest, so a project named like vue-loader no longer gains dependencies (#11700).
• Packages in an external virtualStoreDir can resolve the project's hoisted direct dependencies. Run pnpm install --force to repair an existing installation (#5652).
• The bins of auto-installed peer dependencies are linked into the workspace root's node_modules/.bin (#8511).

Lockfiles#

• pnpm install --frozen-lockfile works on a detached HEAD with gitBranchLockfile (#7672), and accepts a lockfile without an importer entry for a workspace package that has no dependencies (#15875).
• pnpm install fails with ERR_PNPM_LOCKFILE_MISSING_DEPENDENCY when an importer references a dependency version with no snapshot entry (#14764).
• On CI, an explicit preferFrozenLockfile: true no longer lets the install update an outdated lockfile (#9072).

Workspaces and injected packages#

• pnpm install no longer creates a node_modules symlink inside the publishConfig.directory of a package linked with linkDirectory, where a build tool cleaning its output could delete dependency files (#16226).
• An injected workspace dependency that publishes from a publishConfig.directory built by its own prepare script installs correctly (#7811).
• injectWorkspacePackages treats a dependency declared with a relative path, such as workspace:../foo, the same way as a workspace:* one (#10446).
• Workspace discovery skips dot-prefixed directories, so ** no longer matches projects inside .cache (#16250).
• pnpm import keeps the versions pinned by a yarn.lock inside a workspace project (#4385).

Store and caches#

• Files imported from the store follow the umask of the install (#3807), and files already in a shared store keep their owner, group, and mode (#12765).
• Repairing a store file modified through a hard link keeps its inode on Linux and macOS, so other projects are healed at the same time (#3445).
• pnpm warns when it cannot hard link from the store in the pnpm home and falls back to a store on the project's filesystem (#14505).
• The side-effects cache restores symlinks that a build script creates. After upgrading, every package with a build script is built once more (#12859).
• Concurrent installs that share a global virtual store build a package in its slot one at a time (#15568).
• A warm install reuses on-disk metadata for five minutes when the registry sends no ETag (#13976), and honors Cache-Control for registry metadata (#13487) and tarball URL dependencies (#15648).

Patched dependencies#

• pnpm install repairs a lockfile whose patch_hash paths disagree with patchedDependencies, and --frozen-lockfile fails on it with ERR_PNPM_INCONSISTENT_PATCH_HASH (#15336).
• A missing patch file fails the install with ERR_PNPM_PATCH_NOT_FOUND (#5268).
• With nodeLinker: hoisted, a shared copy of a patched dependency is patched only once (#7565).
• engineStrict checks the patched package.json (#9603).
• pnpm patch applies the existing patch to a git-hosted dependency (#9699).

Adding and updating#

• pnpm add <dir> warns when the directory declares peer dependencies (#5523).
• pnpm add --save-types skips deprecated @types/* stubs such as @types/typescript (#15636).
• pnpm version, pnpm add, and pnpm pkg set keep JSON5 style in package.json5 (#15717).

Running scripts#

• pnpm run and pnpm exec no longer auto-install when the root package.json still keeps overrides or similar settings in its pnpm field. They fail and ask to move the settings to pnpm-workspace.yaml (#16278).
• When verifyDepsBeforeRun installs before a filtered command, it installs only the selected projects (#11865).
• pnpm -r run /regexp/ honors tasks dependsOn (#15596).
• pnpm run exits with the code of a script that handles Ctrl+C (#9945), and no longer hangs when a background process keeps a finished script's output open (#5730).
• scriptShell is used even when shellEmulator is enabled (#14719).
• With enableGlobalVirtualStore, dependency build scripts see the workspace root's node_modules/.bin (#15652).
• Install scripts find the bundled node-gyp when pnpm runs through a symlink (#15694).
• Commands run through a dependency's own node_modules/.bin no longer fail with MODULE_NOT_FOUND (#10189).
• pnpx --version and pnpm dlx --version print the pnpm version (#16259).

Publishing and deploying#

• pnpm pack and pnpm publish ship a file that files names even when another entry excludes its directory (#16213), and prune directories that a files exclusion names (#15738).
• pnpm publish waits at least 5 minutes for the registry to answer, fixing "409 Conflict - Failed to save packument" errors (#11454).
• pnpm deploy --prod works with a devEngines.runtime that uses onFail: download (#15703).
• pnpm deploy copies workspace dependencies instead of hard linking them to their sources (#12176), and pnpm deploy --legacy no longer leaves broken links (#9575).

Configuration#

• pnpm config set --location=project inside a workspace package writes to the workspace root's pnpm-workspace.yaml (#13757).
• PNPM_CONFIG_WORKSPACE_DIR is read like other settings (#16275).
• An invalid base64 _password fails with ERR_PNPM_AUTH_INVALID_BASE64 (#16273).
• proxy=false turns proxying off even when proxy environment variables are set.
• A pnpmfile fetchers hook runs once per package (#15584, #15025), a custom resolver's package is re-fetched when its integrity changes (#15670), and invalid readPackage results are rejected (#15730, #15705).

Global packages and pnpm versions#

• Signals such as SIGTERM reach the pnpm version pnpm switches to and the one pnpm with runs (#9948).
• On arm64 musl Linux, switching to a pinned pnpm older than 12 runs the JavaScript package (#10443).
• Global shims work when pnpm runs through a relative symlink, as with Homebrew (#15691).
• pnpm env remove --global deletes Node.js versions in pnpm's store (#8357).
• pnpm self-update no longer suggests a downgrade when minimumReleaseAge holds back latest (#12006).

Windows#

• pnpm run passes arguments to the script as typed, without %VAR% expansion or doubled backslashes (#16257).
• pnpm.exe runs without the Visual C++ Redistributable (#15723).
• .cmd shims keep a % in the project path (#15716) and run tools with non-ASCII paths (#6999, #16217). Bin shims run from Cygwin again (#12845).
• Installing pnpm with npm writes node_modules/.bin shims that run pnpm.exe (#15688).
• Wildcard workspace patterns work when the workspace is on a different drive than the pnpm cache (#16239).
• pnpm setup no longer writes pn.ps1, pnpx.ps1, and pnx.ps1, which failed under restrictive execution policies (#8444), no longer panics on non-ASCII environment variable names (#15684), and expands nested %VAR% references in PNPM_HOME (#13236).

Inspecting dependencies and output#

• pnpm audit fails on unresolvable dependency references (#13638).
• pnpm licenses list reports actual on-disk locations with hoisting (#8589).
• pnpm root prints the configured modulesDir (#9113).
• With --loglevel warn or error, the full output of a failed install script is printed.
• Resolution errors show their cause, such as invalid peer certificate: UnknownIssuer (#9556), and SSH Permission denied (publickey) errors suggest ssh-add -l (#13743).
• Lockfile verification errors carry specific codes and suggest relaxing a policy only when that could help (#14411).

See the v12.8.0 release notes for the complete list of changes.

Minor Changes#

.nvmrc and .node-version in the node shim#

The project-aware global node shim now uses the Node.js version from the nearest .nvmrc or .node-version file when the project does not declare a Node.js runtime in devEngines.runtime or engines.runtime (#4471). A project set up for nvm, fnm, or n gets the right node without further setup:

cd ~/projects/legacy-app
cat .nvmrc       # 20
node --version   # v20.x.x

The nearest directory with a Node.js runtime declaration decides the version. Within one directory, package.json takes precedence over .node-version, which takes precedence over .nvmrc. An .nvmrc value that only nvm can act on, such as system or a custom alias, is ignored. See .nvmrc and .node-version.

pnpm install --allow-build#

pnpm install --allow-build allows or denies a package's lifecycle scripts and records the decision in allowBuilds, as pnpm add --allow-build already did (#15388):

pnpm install --allow-build=esbuild --allow-build='!core-js'

Waiting for published packages#

pnpm publish --publish-wait-timeout <milliseconds> waits for the published versions and their tarballs to become available from the registry. A recursive publish confirms each package before it publishes the packages that depend on it, so a dependent never points at a version its consumers cannot fetch yet. If confirmation times out, the command fails. Set a default in pnpm-workspace.yaml:

publishWaitTimeout: 60000

When pnpm publish -r --report-summary fails after some uploads were accepted, the summary file now lists those packages.

pnpm-workspace.yaml from the workspaces field#

In a repository with no pnpm-workspace.yaml, pnpm install now creates one from the workspaces field of the root package.json and links the listed projects on that same install (#2255). An existing pnpm-workspace.yaml is never changed, and nothing is created with --ignore-workspace. If the workspaces field later differs from packages in pnpm-workspace.yaml, pnpm prints a warning. See Converting from the workspaces field.

--force keeps skipping foreign optional dependencies#

pnpm install --force now keeps skipping optional dependencies whose os, cpu, or libc do not match the host (#6133). It still refetches every package and lifts engineStrict. The new forceIgnoresPlatform setting restores the previous behaviour:

forceIgnoresPlatform: true

Other changes#

• When a project pins a pnpm version or a runtime that another pnpm process is installing at that moment, pnpm now waits a few seconds and then installs and runs a private copy. It used to wait up to five minutes and then use the shared install directory without the lock. pnpm store prune removes any private copy a killed process left behind (#15413).
• pnpm now keeps the blank lines between entries of package.json when it updates the file (#5602).
• pnpm now reads and updates package.json5 manifests, keeping their comments. Workspace discovery prefers package.json, then package.json5, then package.yaml (#15129).
• pnpm init --bare creates a package.json with only the required fields (#15538).
• The reporter setting is now honored from pnpm-workspace.yaml, the global configuration, and PNPM_CONFIG_REPORTER (#4879).
• Configuration files support npm's ${VAR?} placeholder, which expands to an empty string without a warning when VAR is unset (#14404).
• publishConfig["@scope:registry"] now sets the publish registry of a scoped package (#12071).
• Node.js runtime resolution supports Windows ARM64 (#7123).

Security#

• pnpm no longer expands environment variables in a userAgent set in a project's pnpm-workspace.yaml. Such a userAgent is ignored. Before, pnpm sent the variable's value to the configured registry (#15415).
• On Nix, a dependency's bin named like a system utility such as sed can no longer redirect a POSIX bin shim or the pnpm, pn, pnpx, and pnx launchers. Installing again replaces the shims already in node_modules (#14883).
• pnpm no longer treats manifests inside its store, cache, state, or modules directories as workspace projects. A storeDir inside the workspace could let lifecycle scripts of packages in the store run without allowBuilds approval (#15033).
• Packages that run a lifecycle script are no longer hard-linked into the virtual store, so a build script can no longer rewrite the workspace source of an injected package or the store copy it was imported from (#15483).

Patch Changes#

Installing#

• Fixed running out of memory when many packages share a missing peer dependency, mostly with autoInstallPeers: false (#15362).
• pnpm no longer hangs for up to 5 minutes after a pnpm process was killed while setting up the pinned pnpm version. A lock whose owner is gone is taken over at once (#15360).
• Requests to a server whose TLS certificate fails verification now fail at once instead of being retried for more than a minute (#9134).
• On macOS, pnpm falls back to its bundled CA roots when system trust evaluation is unavailable, such as in a sandbox (#15329).
• A warm install uses less CPU while linking packages. On Windows, it could take several times longer than with pnpm 11 (#15439).
• pnpm install now fetches committed submodules of git dependencies (#1470).
• A local tarball replaced at the same path is reinstalled, and --frozen-lockfile rejects it (#2437, #1889).
• Installs that skip devDependencies no longer run pnpm:devPreinstall or prepare scripts (#7065).
• --prod installs no longer install a devDependency that only satisfies an optional peer of a production dependency (#15344).
• pnpm fetch also installs the pnpm version pnpm-lock.yaml pins, so a later pnpm install --offline can switch to it (#11808).
• pnpm install no longer adds allowBuilds placeholders to pnpm-workspace.yaml in CI or without a terminal (#11574).
• pnpm detects the same CI environments as pnpm 11, including AWS CodeBuild.

Resolving and linking#

• A dependency that a package also declares as an optional peer dependency is installed again, for example lightningcss in some vite builds (#8912).
• Removing an entry from overrides now re-resolves the packages it targeted (#4587).
• With trustPolicy: no-downgrade, pnpm resolves the newest matching version that is not a trust downgrade instead of failing (#14176).
• autoDedupe and pnpm dedupe move transitive dependencies to the version a catalog: dependency pins, and pnpm dedupe no longer alternates between two lockfiles when an npm: alias is involved (#15588).
• pnpm install --ignore-pnpmfile keeps pnpmfileChecksum in an up-to-date lockfile (#10944).
• With nodeLinker: hoisted, hoistWorkspacePackages links selected workspace projects and their bins into the root node_modules (#7553), and removed packages' commands are removed from node_modules/.bin (#7568).
• Installing the node package on Windows works again (#15501).

Workspaces and filtering#

• Workspace projects reached through a symlink are installed (#1044).
• A catalog: dependency whose entry points at a workspace project counts as a workspace dependency for ordering and filtering (#15587).
• workspace: ranges match projects with non-semver versions such as 1.0 (#4567) and with build metadata (#6483).
• --frozen-lockfile fails when the lockfile lists a workspace project that is missing (#7667).
• Injected workspace packages get the output of their own prepare, install, and postinstall scripts (#9464).
• A custom modulesDir works with several path segments, with nodeLinker: hoisted, and on the up-to-date fast path (#15484).
• pnpm warns when a workspace install covers a project that has its own pnpm-workspace.yaml (#11724).
• [<since>] compares against the merge base, and selects projects whose catalog versions changed (#9907, #8718).
• --filter selectors are evaluated in order, so a later inclusion can re-include an excluded project (#9354).

Adding, updating, and removing#

• pnpm add saves package.json before running lifecycle scripts (#8627) and saves a requested exact version (#6040).
• pnpm add <pkg>@<version> and pnpm update <pkg>@<version> move a catalog entry onto the named version (#13715).
• pnpm update keeps a range without a save prefix, such as <= 3.0.0, when the new version still satisfies it (#6714).
• pnpm update <pkg> can move off a locked version the registry no longer serves (#9953).
• pnpm unlink removes the link: dependency that pnpm link <dir> added (#4219).
• pnpm install prunes unreferenced catalog entries when catalogPrune: true is set (#15273).
• pnpm import converts Yarn's patch: protocol (#10278).
• pnpm patch and pnpm patch-commit work with sharedWorkspaceLockfile: false (#9926).

Running scripts#

• A script run without a terminal ends when pnpm is killed, for example by Playwright's webServer (#15555).
• pnpm --filter <project> <command> and pnpm -r <command> run a command from the projects' dependencies when no script has that name (#10151).
• pnpm exec and pnpm dlx set npm_execpath, INIT_CWD, npm_node_execpath, and NODE (#7037), and pnpm exec sets PWD (#1550).
• pnpm restart runs stop and start when there is no restart script (#4750).
• pnpm dlx keeps a separate cache entry per Node.js major version (#8611).
• pnpm pipeline runs outside a Git work tree, without caching (#15601).
• A runtime: range such as ^22.18.0 || ^24.0.0 installs the runtime instead of the node npm package (#14817).

Publishing and deploying#

• pnpm publish resolves workspace: dependencies without node_modules (#6567).
• pnpm pack and pnpm publish include bundled dependencies with the isolated linker (#1643), keep symlinks inside the package (#8208), and preserve executable permissions.
• pnpm deploy copies the root packageManager field (#9079), honors virtualStoreDir (#8787), and skips the deployed project's prepare script (#7282).

Global packages and pnpm versions#

• Global commands run with the pnpm you invoked, even in a project that pins another version (#14531).
• pnpm self-update inside a project that pins pnpm also updates the global pnpm (#14747) and no longer leaves the previous @pnpm/exe behind (#14709).
• pnpm setup no longer fails with Text file busy (#15494) and no longer deletes lines near the pnpm block of a shell startup file (#7067).

Windows and WSL#

• Installs and pnpm clean wait for a file held open by another process instead of failing at once, on Windows (#15081) and on Windows drives under WSL (#6155).
• Saving pnpm-lock.yaml is retried while another process holds it open (#9461).
• Trailing dots and spaces are escaped in node_modules/.pnpm directory names (#8101).
• Bin shims run from Git Bash, MSYS2, or Cygwin pass NODE_PATH as Windows paths (#3360).

Inspecting dependencies#

• pnpm audit honors --filter (#10982) and lists a dependency path from every affected workspace project (#12200).
• pnpm list and pnpm licenses list inside a workspace project list only that project (#14494, #5689).
• pnpm list --only-projects prints every selected project (#9770).
• pnpm licenses list works with sharedWorkspaceLockfile: false (#10140) and with nodeLinker: hoisted (#8589).
• pnpm store status no longer reports packages with build scripts as modified (#15383).

See the v12.7.0 release notes for the complete list of changes.

Minor Changes#

forceIgnoresPlatform#

pnpm install --force installs every optional dependency, including those built for another os, cpu, or libc. The new forceIgnoresPlatform setting turns that part off, so --force still refetches packages and lifts engineStrict but skips optional dependencies for other platforms (#6133):

forceIgnoresPlatform: false

The default stays true in pnpm 11. In pnpm 12, --force skips such dependencies by default.

pnpm update --peer#

pnpm update --peer also updates the ranges in peerDependencies, which pnpm update otherwise leaves alone (#8081):

pnpm update --peer react

Security#

• pnpm no longer expands environment variables in a userAgent set in a project's pnpm-workspace.yaml. Such a userAgent is ignored. Before, pnpm sent the variable's value to the configured registry (#15415).
• Packages inside a custom modulesDir are no longer treated as workspace projects. With a modulesDir such as vendor and a packages pattern such as **, a repeat install ran lifecycle scripts that allowBuilds had not approved (#15412).
• On Nix, a dependency's bin named like a system utility such as sed can no longer redirect a POSIX bin shim or the pnpm, pn, pnpx, and pnx launchers. Install again to replace the shims already in node_modules (#14883).
• Shell completion omits candidates containing control or invisible formatting characters, so package and script names can no longer inject completion records or terminal escape sequences.
• pnpm runtime set and pnpm env use no longer run a script that another package installed under the name pnpm or pn as though it were pnpm.
• pnpm store prune leaves a dlx cache root that is a symlink or Windows junction untouched.

Notable fixes#

Installing#

• Requests to a server whose TLS certificate fails verification now fail at once, naming the certificate problem, instead of retrying for more than a minute (#9134).
• Git dependencies fetched over SSH no longer appear to hang on a hidden passphrase or host key prompt: pnpm runs ssh in batch mode, so load a key that needs a passphrase into an SSH agent first (#2227). Committed submodules of git dependencies are now fetched (#1470).
• bzip2-compressed tarballs can be installed (#6761).
• The root project's preinstall script now runs before dependencies are resolved and linked, so a guard such as npx only-allow pnpm stops the install before node_modules is populated (#3760).
• Installs that skip devDependencies, such as pnpm install --prod, no longer run pnpm:devPreinstall or prepare (#7065), and they no longer install a devDependency that only satisfies an optional peer of a production dependency (#15344).
• pnpm install no longer adds allowBuilds placeholders to pnpm-workspace.yaml in CI or without a terminal (#11574).
• pnpm install --engine-strict respects engines relaxed by readPackage hooks (#15482), and the project's pnpmfile now runs after the pnpmfiles of config dependency plugins (#9891).
• pnpm install and pnpm run reinstall a project that was moved together with its node_modules (#9512), and relink a direct dependency whose link points to a missing target (#9758).
• pnpm fetch also installs the pnpm version that pnpm-lock.yaml pins, so a later offline install can switch to it (#11808).
• pnpm no longer crashes when TMPDIR, TEMP, or TMP points to a missing directory (#4960).

Resolving and linking#

• A dependency that a package also declares as an optional peer, such as lightningcss in some vite builds, is now installed (#8912).
• Removing an overrides entry re-resolves the packages it targeted (#4587).
• With trustPolicy: no-downgrade, pnpm resolves the newest matching version that is not a trust downgrade instead of failing (#14176).
• Ranges resolve to the newest matching version that is not deprecated (#15128).
• pnpm add followed by pnpm remove of the same package leaves pnpm-lock.yaml unchanged; unrelated transitive dependencies no longer move (#11859).
• pnpm install --frozen-lockfile succeeds when an optional dependency was unresolvable and skipped by the install that wrote the lockfile (#3960).
• hoistWorkspacePackages works with nodeLinker: hoisted (#7553), and hoisted workspace projects are hoisted on every install, not only after node_modules is deleted (#3642).
• A workspace package's bin that a build script creates after install is now linked (#10007).

Workspaces and filtering#

• --filter "[<since>]" compares against the merge base with <since> (#9907), and selects projects that use a changed catalog entry (#8718).
• --filter selectors are applied in order, so a later inclusion can re-include a project that an earlier exclusion removed (#9354).
• pnpm --filter <project> <command> and pnpm -r <command> run a command installed in the projects' dependencies when none of them has a script by that name (#10151).
• Workspace projects reached through a symlink are installed (#1044).
• A catalog: dependency that points at a workspace project counts as a workspace dependency for ordering and filtering (#15587).
• workspace: ranges match projects whose version is not valid semver, such as 1.0 (#4567), or carries build metadata (#6483).
• pnpm install --filter with nodeLinker: hoisted installs only the selected projects' dependencies (#8882).
• pnpm warns when a workspace install covers a project with its own pnpm-workspace.yaml, whose settings do not apply (#11724).

Custom modulesDir#

• pnpm run, pnpm exec, pnpm version hooks, and install-time lifecycle scripts find commands in a custom modulesDir, and tools installed there can load CommonJS plugins installed next to them (#3604). See extendNodePath.
• A repeat install in a workspace with a custom modulesDir takes the up-to-date fast path.

Adding, updating, and removing#

• pnpm remove runs the project's own preuninstall, uninstall, and postuninstall scripts (#3276), and pnpm remove -r fails before changing any manifest if a dependency is absent from every selected project (#2319).
• pnpm unlink removes the link: dependency that pnpm link <dir> added (#4219).
• pnpm add saves the requested exact version (#6040), writes package.json before lifecycle scripts run (#8627), and keeps a specifier a readPackage hook rewrote (#15156).
• pnpm update keeps ranges such as <= 3.0.0 that the new version still satisfies (#6714), updates auto-installed peers by name (#10486), and moves a package off a locked version the registry no longer serves (#9953).
• minimumReleaseAgeExcludePrune and trustPolicyExcludePrune work with sharedWorkspaceLockfile: false (#14612).
• pnpm import converts Yarn patch: dependencies into patchedDependencies (#10278).

Scripts#

• A script run without a terminal ends when pnpm is killed, as Playwright's webServer does (#15555).
• pnpm exec and pnpm dlx set npm_execpath, INIT_CWD, npm_node_execpath, and NODE (#7037), and pnpm exec sets PWD (#1550).
• pnpm restart runs stop and start when there is no restart script (#4750).
• pnpm install-test accepts --no-bail (#3777).
• pnpm dlx keeps a separate cache per Node.js major version (#8611).
• A runtime: range containing || or a space installs the runtime instead of the npm package of the same name (#14817).

Publishing, packing, and deploying#

• pnpm publish resolves workspace: dependencies without node_modules (#6567) and honors publishConfig["@scope:registry"] (#12071).
• pnpm pack includes bundled dependencies with the isolated linker (#1643), keeps symlinks inside the package (#8208), and preserves executable permissions.
• pnpm deploy copies the root packageManager field (#9079), puts the virtual store at virtualStoreDir (#8787), and no longer runs the deployed project's prepare script (#7282).

Configuration and registries#

• .npmrc files support npm's ${VAR?} placeholder (#14404), and _auth tokens from the global config.yaml or pnpm_config__auth expand environment variables (#12828).
• pnpm login logs back in to an existing user on registries without web login, such as verdaccio (#12055).
• pnpm doctor checks the configured default registry (#15618).
• pnpm preserves CRLF line endings when it modifies manifests.

Windows and WSL#

• pnpm install in WSL waits out Windows file locks on /mnt/c and similar drives (#6155), and saving pnpm-lock.yaml on Windows retries while another process holds it (#9461).
• pnpm add and pnpm update write file: and link: specifiers with forward slashes on Windows (#7497).
• Node.js runtime resolution supports Windows ARM64 (#7123).
• Bin shims run from Git Bash, MSYS2, or Cygwin pass NODE_PATH as Windows paths (#3360).

Inspecting dependencies#

• pnpm audit honors --filter (#10982), lists a path from every affected project (#12200), and --fix=update fixes npm-aliased dependencies (#15155).
• pnpm list and pnpm licenses list inside a workspace package list only that package unless --recursive or --filter is given (#14494, #5689).
• pnpm -r outdated --json includes every outdated dependency when projects use different versions of the same package (#7693).
• The ignored build scripts warning and the update notice print as plain lines in CI and non-terminal output (#9421).

For the complete list of changes, see the v11.28.0 release notes.

Automatic deduplication#

autoDedupe deduplicates compatible dependency versions during installation (#7258). Enable it in pnpm-workspace.yaml:

autoDedupe: true

When a dependency appears at multiple versions and one satisfies every range, pnpm picks that version for the whole workspace. Frozen installs leave the lockfile unchanged.

Relocatable node_modules#

pnpm install, pnpm run, and pnpm exec on macOS and Linux now reuse a node_modules directory and bin shims that moved or were copied together with their project (#6937). The first command after the move checks the tree and records the new location, so project commands in node_modules/.bin keep working.

--save-types#

pnpm add --save-types saves available @types/* packages in devDependencies alongside registry dependencies (#3868):

pnpm add express --save-types
# saves express to dependencies, @types/express to devDependencies

Packages that declare bundled TypeScript types are skipped. Set saveTypes: true in pnpm-workspace.yaml to enable this by default.

package.yaml manifests#

package.yaml manifests can now be updated by pnpm add, pnpm update, pnpm remove, pnpm pkg, pnpm link, pnpm set-script, and pnpm version (#2008). Existing comments and key order are preserved.

file: and link: catalogs#

Catalog entries can now use the file: and link: protocols (#8642). A relative path or bare path in a catalog entry is measured from the directory holding pnpm-workspace.yaml:

catalog:
  my-lib: link:./packages/my-lib
  my-tarball: file:./tarballs/foo.tgz

pnpm tasks status#

pnpm tasks status lists running and waiting tasks in each concurrency group, and waiting tasks now take available slots in order of descending priority, with arrival order used only to break ties (#15208). If workspaces use different limits for the same group, a later task can take a free slot that earlier tasks cannot use. A package script named tasks takes precedence; use pnpm pm tasks status when that script exists.

macOS Time Machine exclusions#

macosBackup.excludeModulesDir and macosBackup.excludeStoreDir on macOS can now exclude newly created modules, virtual-store, and package-store directories from Time Machine (#6440). Set either to true in global configuration or through the PNPM_CONFIG_MACOS_BACKUP_EXCLUDE_MODULES_DIR and PNPM_CONFIG_MACOS_BACKUP_EXCLUDE_STORE_DIR environment variables.

Smaller additions#

• pnpm add --tilde is now an alias for --save-prefix=~ (#12863). The Yarn -T shorthand is not supported.
• progress setting and --no-progress option turn off dependency and download progress lines (#14065). Warnings, lifecycle output, and the dependency summary are still printed.
• pnpm cache prune now also deletes registry metadata cache directories that this version of pnpm can no longer read (#15046). pnpm cache prune --dry-run lists what it would delete without removing anything.

Patch changes#

Security#

• POSIX bin shims now take cygpath and wslpath from the system default path on Cygwin, MSYS2, and WSL2 so a dependency cannot redirect another package's shim (#14866).
• pnpm install deprecation warnings no longer carry the text of a package's deprecation notice, naming only the deprecated package and version (#15099).
• pnpm install and other commands now warn when environment variables in project .npmrc credentials are ignored (#15051).

Installing packages#

• pnpm install --frozen-lockfile now succeeds when an optional dependency was unresolvable and skipped by the install that wrote the lockfile (#3960).
• pnpm install --frozen-lockfile no longer installs dependencies of projects removed from pnpm-workspace.yaml (#15248).
• pnpm ci now empties node_modules before installing in a project that declares a clean script (#15276).
• pnpm install --force now re-imports every package into the virtual store (#15030) and removes obsolete dependency links inside virtual-store packages when their dependencies change (#15039).
• preinstall script for the root project now runs before dependencies are resolved and linked (#3760).
• pnpm install --prod no longer downloads registry packages that only a devDependency reaches (#881).
• pnpm install no longer hangs when a git dependency is fetched over SSH and ssh prompts for a passphrase or host key confirmation (#2227).
• pnpm install now reuses an in-flight tarball download when another resolution of the same archive still needs its package.json (#15037).

Resolving and linking#

• pnpm install and pnpm update now resolve a dependency range to the newest matching version that is not deprecated (#15128).
• pnpm add <pkg> without a version now uses the catalog entry when the workspace already catalogs that package (#14865).
• pnpm.overrides entries written as a bare path are now measured from the directory holding pnpm-workspace.yaml (#11131).
• pnpm peers check and strict peer dependency checks no longer reject compatible versions from named registries (#15225).
• pnpm outdated and pnpm update --interactive --latest now include named-registry dependencies and preserve their registry prefix (#15226).
• Sped up pnpm dedupe and pnpm install in projects with many convergence overrides by checking overrides concurrently (#15175).

Running scripts#

• pnpm run signal handling no longer delivers a redundant second SIGINT on Ctrl+C, and properly forwards termination signals without a terminal (#7374).
• pnpm test now forwards --filter arguments to the test script when the option follows the shortcut (#15217).
• pnpm deploy, pnpm rebuild, pnpm rb, and pnpm setup now prefer a package.json script of the same name (#14976).

Configuration#

• pnpm-workspace.yaml edits now preserve scalar YAML anchors and aliases (#8245).
• pnpmfile configuration now loads a .js file as CommonJS or an ES module, following the nearest package.json (#15141).
• readPackage hook changes now take added dependencies out of pnpm-lock.yaml and update dependencies when an existing lockfile is present (#3735, #15136).
• pnpm now preserves CRLF line endings when modifying project manifests (#3529).
• storeDir values loaded from global configuration now expand a leading ~/ to the user's home directory (#6560).

Windows#

• pnpm install on Windows now runs dependency build scripts from long global virtual store paths (#15111).
• pnpm install across projects sharing a global virtual store on Windows no longer fails with Access is denied or file-exists errors (#15114, #15176).
• pn, pnpx, pnx, and pnpm now run when Git Bash, MSYS2, or Cygwin launches them through a Windows path (#14884).
• pnpm pipeline --watch now resolves Windows short paths so multiple path representations share the build cache (#15105).

Other fixes#

• pnpm remove now runs preuninstall, uninstall, and postuninstall scripts (#3276).
• pnpm remove -r now fails before modifying manifests if any requested dependency is absent from all selected projects (#2319).
• pnpm update --peer now updates ranges in peerDependencies (#8081).
• pnpm update -g no longer reinstalls unchanged packages (#12002).
• pnpm publish now allows a detached Git HEAD in CI environments (#5894).
• pnpm store prune now removes unreferenced files from the content-addressable store (#3635) and expired pnpm dlx cache data (#15171).
• pnpm deploy no longer triggers an install when running scripts in a read-only deployed filesystem (#11617).
• pnpm sbom now validates SPDX identifiers before emitting them as CycloneDX license IDs (#14786).
• pnpm --filter and pnpm -F shell completion now suggests workspace package names (#15216).
• pnpm run shell completion now suggests package scripts (#15034).
• pnpm --version no longer creates a temporary file in the project directory (#15264).

See the v12.6.0 release notes for the complete list of changes.

Python projects and environments#

Interpreters per project#

pnpm install chooses an interpreter that satisfies each project's requires-python, preferring .python-version when present. Different projects can use different interpreters. Set python.executable to choose one interpreter for every project.

When no installed interpreter fits, pnpm downloads a shared python-build-standalone interpreter and reuses it on later installs. runtimeOnFail controls this behavior: download permits downloads, error fails, and warn or ignore use an available interpreter despite the version mismatch.

Environments now live under python-envs in the pnpm store. Each project keeps its .venv link, which the next install migrates from the old project-local layout. Old .pnpm/python-envs directories remain until you delete them after running programs stop using them. With frozenStore, environments remain local.

Wheel imports use packageImportMethod. Choose clone-or-copy or copy when installed files may be modified. Isolated build environments use clones or copies to keep backend writes private.

Editable packages and workspace sources#

pnpm now installs a Python project's own package editable when it declares [build-system], so its imports and [project.scripts] commands work immediately. [tool.uv].package can override whether it is packaged. Dynamic metadata comes from the build backend, and projects with only requirements.txt can receive an environment and lockfile too.

Declare local dependencies through [tool.uv.sources]:

[tool.uv.sources]
shared = { workspace = true }
# Alternatively: shared = { path = "../shared", editable = true }

Build backends need approval through allowBuilds, using keys such as 'pkg:pypi/hatchling': true. Git dependencies and source distributions are also supported and require distribution approval. Direct wheel URLs are supported. A workspace dependency without a source declaration is refused instead of silently fetched from an index.

One environment for a uv workspace#

Members can share one environment:

[tool.uv.workspace]
members = ["packages/*"]

[tool.pnpm.python]
shared-environment = true

pnpm resolves every member into one pylock.toml and one .venv at the root. Conflicting dependency requirements produce an error naming the members. Independent environments remain the default.

Each project can also select its own extras and dependency groups under [tool.pnpm.python]. Workspace defaults skip names a project does not define; explicit project selections must exist.

One lockfile for multiple environments#

Combine platform targets with Python versions:

supportedArchitectures:
  - linux-x64-manylinux_2_28
  - darwin-arm64
  - win32-x64
python:
  enabled: true
  versions: ['3.12', '3.13']

Every platform is paired with every version. One pylock.toml pins wheels and conditional dependencies for all of them. Installs select their matching environment and reject interpreters outside the declared environments.

python.overrides and python.constraints control versions throughout the graph. uv overrides and constraints are read too. Python filtering now selects projects by name, path, and local-source dependency relationships; pnpm add --filter <selector> pypi:<package> updates every selected project.

Package URLs and ecosystem registries#

pnpm add accepts Package URLs:

pnpm add pkg:npm/express@4.18.2
pnpm add pkg:cargo/serde@1.0.188
pnpm add pkg:pypi/requests@2.31.0

Each writes to its ecosystem's manifest. pkg is now a reserved registry alias, regardless of case.

registries entries can name ecosystem: npm, cargo, or pypi. Each Python index declares the names it serves with packages, and a package resolves only from the index that claims it — declaration order carries no meaning, and a missing package or a registry error never falls back to another index. Cargo accepts one sparse index. Credentials come from .npmrc, matched by origin; registry URL keys cannot contain credentials.

registries:
  https://packages.example.org/simple/:
    ecosystem: pypi
    packages: ["company-*"]
  https://pypi.org/simple/:
    ecosystem: pypi
    packages: ["*"]

Name-based routing arrived in 12.5.1; 12.5.0 searched the indexes in declaration order.

This replaces python.indexUrl, python.extraIndexUrls, and cargo.indexUrl. Without ecosystem declarations, PyPI and crates.io remain the defaults.

Platforms, tasks, and tool mirrors#

supportedArchitectures accepts a list of exact platforms, such as linux-x64, linux-x64-musl, and darwin-arm64, or Rust target triples. current names the install's platform. The existing os, cpu, and libc mapping still works.

concurrencyGroups limits tasks across pnpm processes on the same machine, including pipelines:

tasks:
  test:rust:
    concurrencyGroup: cargo
concurrencyGroups:
  cargo: 2

A nested pnpm run in the same group reuses its parent's slot.

tools configures mirrors for Node.js, Bun, and Python in global config.yaml or PNPM_CONFIG_TOOLS. Node.js also supports per-channel mirrors. Workspace tool mirrors are ignored, and pnpm pack-app uses tools.node for its embedded runtime.

Cache cleanup and other fixes#

• pnpm cache prune removes obsolete metadata directories left by the registry cache naming change. Use --dry-run to preview deletions. pnpm cache list-registries now prints full URLs instead of encoded names.
• Downloads no longer reuse a tarball for another package whose resolution pins a different integrity hash to the same URL (#15021).
• Production and development install filters keep the complete dependency graph in pnpm-lock.yaml, so a later frozen install accepts it (#14912).
• Lockfile Git conflict markers are merged automatically (#14880).
• Cargo lockfile generation supports path and Git source overrides, and vendoring includes recursive Git submodules at their pinned commits.
• pnx and pnpm dlx prompt for dependency build approval in interactive terminals, including cached installs with pending builds.
• Python projects prepare concurrently, and identical registry requirements share fresh resolutions. pnpm audit also avoids hangs on graphs with many shared dependencies.

See the v12.5.0 release notes for the complete list of changes.