pnpm 12.17.0: Global Peer Checks and Override Selectors

A global install of a package can leave peer dependency problems that only show up when you look at global packages. pnpm 12.17.0 addresses this with a new check flag and a warning that points to it. The mechanism runs in five steps, and the sections below expand each one.

1. You run a global install or update of a package.
2. The peer dependency warning now suggests pnpm peers check -g.
3. pnpm peers check --global checks the globally installed packages.
4. Override selectors can target one dependency group with :prod, :optional or :peer, and * wildcards match parent and target package names.
5. When cargo.enabled or python.enabled is set, pnpm outdated and pnpm update also read Cargo and Python files.

Checking globally installed packages with pnpm peers check -g #

The release adds a --global option to pnpm peers check, with -g as its short form. The notes describe it as a way to check globally installed packages, and the same release changes the peer dependency warning shown after a global install or update so that it suggests this check (pnpm 12.17.0 release notes, issue #17504). The commands are:

pnpm peers check --global
pnpm peers check -g

pnpm peers check now accepts --global ( -g ) to check globally installed packages.

pnpm 12.17.0 release notes

For someone who installs command-line tools globally, the warning now names a command to run next, instead of only reporting the problem. The check covers global packages, which is the scope the notes describe. This suggests that a project-level check does not replace it for globally installed tools.

Overrides that target a single dependency group #

Override selectors now accept :prod, :optional and :peer pseudo-selectors, and the notes say each one targets a single dependency group. They also accept * wildcard patterns on both the parent and the target package name. Taken together, a selector can be limited to one group, and a wildcard can match several package names in one entry. The notes do not show override syntax examples, so the exact selector form has to come from the release documentation.

The release also changes what some override values do. An override with a non-range value, such as npm: or file:, no longer adds a peer dependency to dependencies. Removing an optional dependency with "-" now also removes its duplicate entry from dependencies (issue #5391). If your overrides use those value forms, check dependencies after the next install, since the notes say the entry is no longer added.

Runtime and package manager versions in outdated and update #

pnpm outdated and pnpm update now inspect and update the package manager and runtime versions declared in these fields:

• devEngines.packageManager
• packageManager
• devEngines.runtime
• engines.runtime
• runtime: dependencies

The pinned packageManager and runtime entries of a project therefore appear in the same outdated and update workflow as ordinary dependencies. Runtime and package manager versions are now part of the check, which suggests that a project pinning pnpm or Node.js in these fields will see those pins listed as outdated when a newer version exists. This is an inference from the notes, which list the fields and the commands but not the output format.

Cargo and Python dependencies behind cargo.enabled and python.enabled #

When cargo.enabled or python.enabled is set, pnpm outdated and pnpm update also inspect and update Cargo dependencies in Cargo.toml and Cargo.lock and Python dependencies in pyproject.toml and pylock.toml. The notes tie these files to those two settings, so a project that uses neither setting should not expect these files in the output. This suggests that a mixed JavaScript, Rust and Python repository needs those keys set before its update run covers all three ecosystems.

The runtime setting that controls runtime installs #

An earlier release defined what the runtime setting does. The pnpm 12.16.0 release notes say that setting runtime: false in pnpm-workspace.yaml, pnpm_config_runtime=false, or --config.runtime=false stops installing commands from installing the runtimes in devEngines.runtime and engines.runtime. The same notes add pnpm dedupe --no-runtime.

Read together with the 12.17.0 change, the runtime entries that outdated and update now inspect are the same ones this setting controls for installs. runtime: false therefore governs installing those runtimes, while the 12.17.0 notes cover checking and updating their version fields. This is a reading of two sets of notes that the sources do not connect explicitly.

Script and shell behaviour changes to check #

Three behaviour changes affect scripts. First, pnpm --env-file now reads files the way node --env-file does. Values are taken as written, so $VAR is no longer expanded, and Windows paths such as C:\Users\me load unchanged. A file is no longer rejected for its contents. Any .env file that relied on variable expansion needs its values rewritten.

Second, programs that a script or pnpm exec leaves running now outlive pnpm exactly when they would outlive the command run without pnpm. When a recursive or parallel run bails, scripts still running receive SIGTERM on Unix and are killed only if they still run two seconds later. On Windows, everything those scripts started is ended, including detached processes whose parent has exited. Third, the Windows shim changed: a .cmd or .bat bin now runs under Git Bash when MSYS argument conversion is off, such as with MSYS_NO_PATHCONV=1 or MSYS2_ARG_CONV_EXCL='*', and no longer starts an interactive cmd.exe prompt (issue #17480).

pnx and pnpm create now run the command in the directory chosen by --dir or --workspace-root. Without either flag, they still run in the directory where pnpm started.

Files pnpm writes with umask permissions for Docker images #

Files that pnpm creates now get the permissions the umask gives any new file, such as 0644. The notes say several of them were readable only by the user who ran pnpm, which broke Docker images that run as a different user (issue #17435). A different user running pnpm run reinstalled dependencies because it could not read node_modules/.pnpm-workspace-state-v1.json. The fix covers:

• node_modules/.pnpm-workspace-state-v1.json
• pnpm-workspace.yaml
• the files written by pnpm deploy
• patch files from pnpm patch-commit
• the lockfile restored by pnpm dedupe --check
• the Cargo and Python files that pnpm writes

When pnpm edits an existing file, the file keeps its permissions. For a Docker image that runs installs as one user and runs scripts as another, this suggests checking that the state file is readable by the second user after the install.

Also in this release #

The remaining 12.17.0 items are listed here in short form:

• Commands installed with pnpm add --global find the dependencies pnpm hoists for their package (issue #17503); reinstall such a package to update its command.
• When pnpm switches to a pinned version, it installs that version's native binary for the current host, even when supportedArchitectures excludes the host.
• With the global virtual store, a change in a dependency cycle gives every package in that cycle a new directory (issue #17466). Those packages move once after this update.
• With nodeLinker: hoisted, each workspace project keeps its own copy of a package that cannot be hoisted to the root (issue #17498).
• The Node.js latest selector chooses the newest stable release (issue #17490).
• Hardlinking from the store stats each store file once per install. The notes give 15% system CPU on an offline install of a large workspace (issue #17500).
• Repeat installs no longer report an outdated lockfile after the install that wrote it, for local directory and injected workspace dependencies (issues #17447, #17473).
• Repeat installs now relink a workspace: or link: dependency whose link was deleted (issue #17485).
• pnpm install and verifyDepsBeforeRun run the pnpmfile's readPackage hook on the edited manifest before comparing it with the lockfile.
• pnpm update --latest with package selectors updates the selected packages within their ranges, and excluded packages keep their locked versions (issue #17444).
• pnpm add with a catalog entry set to the same dist-tag saves catalog: and leaves the entry as written (pnpm/tasks#225).
• pnpm add v2@npm:vue saves the npm alias range as npm:vue@^3.5.13.
• pnpm version creates no git commit or tag when gitTagVersion is false (issue #17460).
• pnpm publish reads publishBranch from pnpm-workspace.yaml and PNPM_CONFIG_PUBLISH_BRANCH; --publish-branch overrides it.
• pnpm accepts --strict-ssl and --local-address <ip> on the command line.
• pnpm doctor uses a 15-second timeout for registry connectivity.
• Parse errors in pnpm-workspace.yaml report ERR_PNPM_INVALID_SETTING.
• The invalid dependency name error now names the project's directory (issue #17475).