pnpm release notes, breaking changes, and upgrade notes.
Fast, disk space efficient package manager StackPulse turns upstream changelogs into scannable summaries with risky changes, deprecations, migration notes, and source links.
This release introduces several new features and improvements, including better handling of workspace dependencies, atomic global installs, and performance optimizations for peer dependency resolution. It also includes various bug fixes and stability improvements.
affected
Users of pnpm, especially those using workspaces, catalogs, or global installs, will benefit from improved performance, stability, and new features.
action
Update to this release to take advantage of new features and performance improvements, especially if using workspaces or global installs.
release_signals
!Renamed `cleanupUnusedCatalogs` to `catalogPrune`. `cleanupUnusedCatalogs` continues to work but `catalogPrune` takes precedence when both are set.
+Added `minimumReleaseAgeExcludePrune` setting to automatically clean up `minimumReleaseAgeExclude` entries in `pnpm-workspace.yaml`.
+Added `syncInjectedDepsAfterScripts` setting to synchronize injected dependencies after specified scripts.
+Global installs now switch over atomically, preventing missing commands during installs.
+Improved memory usage and speed for resolving peer dependencies in workspaces with many cycles.
+`pnpm deploy` now injects workspace dependencies, making the deploy directory self-contained.
This release changes how POSIX command shims handle targets without interpreters, now executing them directly instead of waiting. This fixes incorrect exit code reporting for signal-terminated processes.
affected
Users relying on POSIX command shims behavior for signal handling in CI runners or process supervisors may be affected.
action
Test the new shim behavior in your CI pipelines if you rely on signal exit codes.
This release candidate introduces a new `globalShims` feature for managing globally installed binaries per-project, along with several compatibility and performance improvements. It also fixes issues with registry compatibility for version switching and self-updates.
affected
Developers using globally installed binaries or managing Node.js versions per-project are affected by the new global shims feature.
action
Review the new `globalShims` setting and adjust it according to your project's needs for globally installed binaries.
release_signals
+New `globalShims` setting allows globally installed binaries to follow project-specific configurations, with policies for package trust and runtime version management.
+Improved `pnpm dlx` and `pnpm create` compatibility with projects using `patchedDependencies`.
v11.21.0mediumbreakingfeatureAug 9, 2026
pnpm 11.21
This release introduces interactive group selection for global updates and warns about sudo usage for global commands, which will become an error in v12. It also includes various fixes for dependency resolution, Git repository handling, and lockfile verification.
affected
Users running pnpm global commands with sudo will be affected by the upcoming breaking change in v12.
action
Avoid using sudo with pnpm global commands to prevent issues in future versions.
release_signals
-Running `pnpm setup`, `pnpm self-update`, or global modification commands through `sudo` will fail with `ERR_PNPM_SUDO_NOT_SUPPORTED` in pnpm v12.
+Added interactive group selection to `pnpm update --global --interactive`.
pnpm 12 RC 1 introduces significant changes to how Git dependencies are handled, treating them as identities rather than transport choices, and adds new features like interactive group selection for updates. It also includes various performance improvements and bug fixes.
affected
Users relying on SSH URLs for Git dependencies from known hosts (GitHub, GitLab, Bitbucket) will need to configure global Git URL rewriting if they require SSH access.
action
Configure global Git URL rewriting if SSH access to private repositories is required.
release_signals
-Git dependencies on known hosts (GitHub, GitLab, Bitbucket) are now treated as identities rather than transport choices. SSH URLs for these hosts are no longer recorded in the lockfile, resolving to the host's canonical HTTPS URL instead. To use SSH for private repositories, configure git's URL rewriting globally.
v12.0.0-rc.0highbreakingprereleaseAug 5, 2026
pnpm 12 RC 0
This release candidate introduces a breaking change for sudo usage with global commands and fixes several bugs related to file handling, lockfile parsing, and installation behavior.
affected
Users who rely on `sudo` for global pnpm commands will need to adjust their workflows.
action
Avoid using `sudo` with pnpm global commands; they are designed to work without root permissions.
release_signals
-Running `pnpm setup`, `pnpm self-update`, or global modification commands through `sudo` now fails with `ERR_PNPM_SUDO_NOT_SUPPORTED` instead of silently operating on the root user's home directory.
This release addresses a critical security vulnerability in projects using `namedRegistries` by introducing registry-qualified keys in the lockfile. It also adds a built-in `npmjs:` alias and improves dependency resolution performance.
affected
Projects using `namedRegistries` are affected by the security fix and lockfile format change.
action
Upgrade to pnpm v11.20.0 immediately if using `namedRegistries` to mitigate package substitution risks.
release_signals
-Lockfile format change for projects using `namedRegistries`: packages are now recorded under registry-qualified keys (e.g., `foo@work:1.0.0`) to prevent package substitution risks. This is a semi-breaking change for affected projects.
This release introduces a critical security fix for projects using `namedRegistries` in pnpm 11.1.0–11.19.x, addressing a package-substitution vulnerability. It also includes performance improvements for workspace installations and peer dependency resolution.
affected
Projects using `namedRegistries` in pnpm 11.1.0–11.19.x are affected by the security fix and must upgrade.
action
Upgrade to pnpm 12 Beta 4 and perform a non-frozen install to re-key lockfile entries.
release_signals
-Projects using `namedRegistries` must upgrade to avoid package-substitution risks. Lockfile entries are re-keyed, requiring a non-frozen install and review.
v12.0.0-beta.3mediumfeatureprereleaseAug 1, 2026
pnpm 12 Beta 3
This beta release of pnpm 12 focuses on performance improvements and bug fixes, particularly around dependency resolution and lockfile handling. Key changes include optimizations for faster dependency resolution and reduced memory usage in complex dependency graphs.
affected
Users with complex dependency graphs or those using `excludeLinksFromLockfile` may be affected by changes in dependency resolution and lockfile behavior.
action
Test the beta version in a controlled environment before upgrading to ensure compatibility with your project's dependency structure.
release_signals
+Improved dependency resolution speed by optimizing package metadata filtering and semver parsing.
+Reduced memory usage for peer-heavy dependency graphs and nested hoisted graphs.
This release improves non-interactive login support, git-hosted package build approvals, and exact version pinning behavior. It also includes several bug fixes related to dependency management and workspace handling.
affected
Users relying on non-interactive `pnpm login`, git-hosted package builds, or exact version pins will benefit from the improvements.
action
Update to pnpm v11.19.0 to benefit from improved non-interactive login and git-hosted package build support.
release_signals
+`pnpm login` now supports non-interactive web-based login without requiring a TTY
+`save-prefix` setting now accepts `=` for explicit version pinning
+`allowBuilds` entries can now approve git-hosted packages by repository URL without commit hash
This beta release improves lockfile handling by warning instead of failing on broken lockfiles, and optimizes installs by skipping incompatible optional dependencies.
affected
Users relying on pnpm's lockfile parsing behavior or optional dependency downloads may be affected.
action
Review lockfile handling behavior if your workflow depends on strict lockfile validation.
release_signals
+`pnpm install` now handles broken lockfiles gracefully with a warning instead of failing.
+Fresh installs skip downloading platform-specific optional dependencies that don't match the current platform.
This beta release introduces significant performance improvements for peer resolution in large workspaces, adds support for non-interactive login, and includes several new features and bug fixes.
affected
Users of large multi-importer workspaces, those using git-hosted packages, or those with large lockfiles will see significant performance improvements and bug fixes.
action
Update to the beta version to test performance improvements and new features in your development environment.
release_signals
+Significantly faster peer resolution in large multi-importer workspaces.
+`pnpm login` now supports non-interactive terminals with web-based login.
+Added `projects[].dependencyManifest` to `@pnpm/napi` install options.
This beta release introduces several new features and breaking changes, including enhanced workspace protocol support, improved `self-update` security, and new configuration options for dependency management.
affected
Users relying on project-specific configurations for `pnpm self-update` or workspace protocol behaviors may need to adjust their workflows.
action
Review project configurations and update workflows to accommodate the new `self-update` and workspace protocol behaviors.
release_signals
-`pnpm self-update` no longer takes any instruction from the project it is run in, including registry, auth configuration, or pnpmfile settings.
-`pnpm update --workspace` now fails with `ERR_PNPM_WORKSPACE_PACKAGE_NOT_FOUND` if a dependency is not in the workspace, and combining it with `--latest` fails with `ERR_PNPM_BAD_OPTIONS`.
v11.18.0highbreakingfeatureJul 29, 2026
pnpm 11.18
This release introduces stricter security for `pnpm self-update`, adds support for publishing packages under different names, and improves handling of optional and local dependencies. Several performance optimizations and bug fixes are also included.
affected
Users relying on project-specific configurations for `pnpm self-update` or managing optional dependencies with missing required dependencies are affected.
action
Review project configurations for `pnpm self-update` and ensure optional dependencies have their required dependencies available.
release_signals
-`pnpm self-update` no longer takes any instruction from the project it is run in, including registry, auth configuration, or `.pnpmfile.(c|m)js` settings. This prevents projects from redirecting downloads or weakening security checks.
This release introduces improvements to `pnpm setup` for GitHub Actions and refines dependency update behavior, particularly for GitHub Actions and non-npm registry dependencies.
affected
Users relying on GitHub Actions workflows or non-npm registry dependencies may be affected.
action
Update to this version if you use GitHub Actions or need improved handling of non-npm registry dependencies.
release_signals
+`pnpm setup` now appends `PNPM_HOME` and the global bin directory to GitHub Actions environment files (`GITHUB_ENV` and `GITHUB_PATH`).
This alpha release of pnpm 12 focuses on improving CLI parity with TypeScript pnpm CLI and enhancing the `pnpm publish` and `pnpm update` commands. Key changes include universal `--registry` support, `--allow-build` for `pnpm add`, and improved handling of `npm:` aliases in `pnpm update --latest`.
affected
Users relying on CLI parity with TypeScript pnpm CLI or using `npm:` aliases in `pnpm update --latest` will benefit from these changes.
action
Test the alpha release to ensure compatibility with your workflows.
release_signals
+`--registry <url>` is now accepted on every command as a universal rc-option.
+`pnpm add` now accepts `--allow-build=<pkg>` to append packages to `allowBuilds`.
+`--dir` / `-C` is now position-independent on the command line.
This release introduces a new `update.githubActionsServer` setting for custom GitHub server URLs, adds the `pnpm unpublish` command, and improves handling of GitHub Actions dependencies. It also includes several patches addressing token polling security, `pnpm install --no-runtime`, and `pnpm update --latest` behavior.
affected
Users relying on GitHub Actions dependencies or needing to unpublish packages will benefit from the new features.
action
Update to this version to take advantage of new features and security improvements.
release_signals
!Token poll for web-based authentication now caps response body at 64 KiB to prevent memory exhaustion attacks.
+Added `update.githubActionsServer` setting for custom GitHub server URLs.
v11.17.0mediumfeaturesecurityJul 23, 2026
pnpm 11.17
This release introduces a new setting for GitHub Actions server URL configuration, improves handling of GitHub Actions dependencies, and includes several bug fixes and security enhancements.
affected
Users relying on GitHub Actions or web-based authentication may be affected by the changes.
action
Update to version 11.17.0 to benefit from the new features and security improvements.
release_signals
!Token poll for web-based authentication now caps the response body at 64 KiB to prevent memory exhaustion by malicious or compromised registries.
+Added `update.githubActionsServer` setting for specifying the base URL of the GitHub server hosting GitHub Actions repositories.
This release addresses critical issues with `catalog:` references in dependencies and overrides, ensuring they resolve correctly when installing through a pnpr server. Additionally, it fixes a crash on Windows when installing nested workspace members.
affected
Users experiencing issues with `catalog:` references or installing nested workspace members on Windows are affected.
action
Update to this version to resolve the mentioned issues.
-Named registry aliases that shadow reserved dependency specifier prefixes (e.g., `file`, `link`) are now rejected with `ERR_PNPM_RESERVED_NAMED_REGISTRY_NAME`.
!Fixed a package substitution vulnerability where dependencies declared against one registry could be satisfied by entries from another registry.
!`pnpm rebuild` now rejects lockfiles with path traversal in package names to prevent execution of malicious lifecycle scripts.
!`@pnpm/util.lex-comparator` and `@pnpm/config.nerf-dart` are deprecated in favor of `@pnpm/text.ordinal-comparator` and `@pnpm/config.registry-auth-key`.
+New built-in `npmjs:` alias resolves to `https://registry.npmjs.org/` by default, allowing dependencies to be pinned to the public registry.
+Improved dependency resolution performance by filtering package metadata once per packument and reusing parsed semver versions.
migration_steps3 steps
01Commit the lockfile diff after a non-frozen install to apply the registry-qualified keys fix.
02Ensure all team members use pnpm v11.20.0 or newer to avoid lockfile flip-flopping.
03Override the built-in `npmjs:` alias if using a mirror or proxy for npmjs.