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 patch release fixes numerous bugs affecting peer dependency selection, frozen-lockfile installs, dependency resolution, and the hoisted node linker. It also hardens registry handling so unresolved environment-variable placeholders in registry URLs fail instead of silently resolving packages from another registry, and updates bundled node-gyp to remove undici 6 flagged for CVE-2026-84947.
affected
Users of pnpm workspaces, frozen-lockfile installs, peer dependencies, or the hoisted node linker benefit from fixes; users of remote resolution or shared build caches with older pnpr servers must upgrade those servers.
action
If you use remote resolution or shared build caches, upgrade pnpr to 0.1.0-alpha.20 or newer before upgrading pnpm.
release_signals
-Remote resolution and shared build caches no longer work with pnpr 0.1.0-alpha.19 or older; pnpr servers must advertise compatible capabilities under `pnpr.protocols` for requested resolution and verification policies.
!Registry URLs containing `${VAR}` placeholders in `pnpm-workspace.yaml` or project `.npmrc` now cause the command to fail, preventing silent resolution from another registry. pnpm does not expand environment variables in these files.
!Bundled node-gyp no longer ships undici 6, which security scanners flag for CVE-2026-84947.
migration_steps1 steps
01Upgrade the pnpr server before upgrading pnpm if using remote resolution or shared build caches; pnpr 0.1.0-alpha.20 or newer is required.
This release stores registries, accounts, and tokens in the database, enabling replicas to share registry configuration and administrators to manage it without a config deploy. It restricts publishing to package owners and admins by default, adds 90-day default token expiry, and includes security fixes for web login links and private upstream credentials. Upgrading from alpha.19 requires a fresh store and database; existing data is not migrated, and many configuration keys and commands have changed or been removed.
affected
Operators upgrading from alpha.19 must rebuild state and adapt configuration, while registry administrators, package publishers, and token users are affected by the new database-backed management and access defaults.
action
Before upgrading, back up the hosted store and databases, prepare an empty store and database, and follow the alpha.19 migration and configuration-renaming steps in the release notes.
pnpm 12.20.0 adds local-directory dependency specifier recording to experimental v13 lockfiles, with frozen installs detecting changed specifiers. It also fixes numerous dependency resolution, hoisted linker, peer dependency, lockfile, and command issues, and updates pnpr protocol compatibility checks.
affected
Users relying on pnpr remote features with older servers must upgrade those servers; users of bundled node-gyp and projects with dependency, peer, or hoisted-linker edge cases also benefit from fixes.
action
Upgrade older pnpr servers before continuing to use remote resolution, shared build caches, or release notes with this pnpm version.
release_signals
-Remote resolution, shared build caches, and release notes are incompatible with pnpr 0.1.0-alpha.19 or older; pnpm now requires the server to advertise and confirm the requested resolution and verification policies.
This release adds PostgreSQL and MySQL metadata storage, deduplicates identical hosted archives, and introduces `pnpr gc` to reclaim unreferenced archives while the registry remains available. It also includes a URL-credential logging fix and changes authentication, account, team, publishing, and registry behavior. Alpha.18 data is not migrated, and the release notes describe substantial upgrade steps.
affected
Operators upgrading from alpha.18 must plan a database and storage transition and may need to recreate accounts, tokens, and published packages; registry users are also affected by stricter authentication and publishing validation.
action
Before upgrading, back up the alpha.18 databases and follow the release's upgrade steps, including configuring fresh storage and replacing the old database configuration.
pnpm 12.19.0 adds the `pnpm fund` command, new dependency-linking and optional-peer behavior, and an experimental JSON-like lockfile format. It fixes an offline-install error that could expose registry credentials and includes numerous install, workspace validation, platform, and linker fixes.
affected
The release affects pnpm users, especially workspace maintainers, users of the `loaded` linker or optional peers, and projects relying on platform-specific dependencies or workspace-wide engine checks.
action
Review workspace engine and platform requirements and, when adopting the `loaded` linker, configure `sideEffectsCache.exclude` for packages whose build must run in every project.
release_signals
-Install and mutation commands now check `engines`, `os`, `cpu`, and `libc` for every workspace project, including the root. Incompatible `engines.pnpm` fails the command; incompatible `engines.node` warns or fails with `engineStrict`; unsupported platforms warn.
This prerelease moves hosted package metadata to SQLite or shared libSQL, adds publication records and release notes, and introduces platform-variant publishing alongside release records logged in transparency logs. It also tightens validation and atomicity for publishes, while removing the documents metadata backend and changing storage behavior for tar-based registries.
affected
Registry operators upgrading from earlier pnpr versions are most affected, especially those using document metadata, S3 storage, or `tarballs: tar`; publishers and clients also gain new publication, variant, and release-record behavior.
action
Review metadata and tarball storage configuration before upgrading, and plan to republish packages where the release notes specify that prior metadata or versions will not be served.
This prerelease changes package and hosted-storage layouts, removes legacy commands, flag aliases, environment variables, and snake_case configuration keys, and updates batch-publish endpoints. It fixes two security issues, improves libsql/Turso authentication database reliability, and includes publishing, installation, and authentication fixes.
affected
pnpr operators must account for the incompatible storage layout, removed commands and aliases, camelCase configuration, and changed batch-publish endpoint; users of libsql or Turso auth databases and metrics endpoints also see relevant fixes and behavior changes.
action
Before upgrading, republish packages into an empty store and update configuration, TTL settings, and batch-publish clients as described in the release notes.
pnpm 12.16 adds environment-file loading, support for updating symlinked lockfiles under configured target directories, and an option to set up pnpm without modifying PATH. It also includes security fixes for zstd decompression and signing, alongside improvements to installation behavior, workspace handling, and lockfile resolution.
affected
The release affects pnpm users configuring environment files, symlinked lockfiles, or setup behavior, as well as users with installations that no longer match current settings and users relying on the affected security-sensitive features.
action
Upgrade to pnpm 12.16.0 to receive the signing and zstd security fixes, and run `pnpm install` if package-management commands report that `node_modules` does not match current settings.
release_signals
-`pnpm add`, `pnpm remove`, and `pnpm update` now fail with specific errors when `node_modules` does not match current settings; run `pnpm install` to recreate it.
pnpr 0.1.0-alpha.16 introduces significant changes to storage layout and configuration validation, replacing deprecated fields with `artifacts.orgs` and requiring migration of existing stores. New features include ecosystem-specific URL prefixes, tar registries, npm audit endpoints, and Prometheus metrics.
affected
Users of pnpr with existing storage layouts or configurations using deprecated fields will need to migrate to the new layout and update their configurations.
action
Back up existing stores and run `pnpr upgrade-storage` to migrate to the new layout, and update configurations to use the new `artifacts.orgs` and `registries` settings.
release_signals
v11.28.7highbreakingfeaturesecurityOct 21, 2026
pnpm 11.28.7
This release introduces security enhancements by rejecting mismatched registry metadata and applying trust policies to pinned pnpm versions. It also adds a new setting to cap unpacked package size and removes support for registry revisions.
affected
Users relying on registry revisions or `pnpm update --patches` will be affected by breaking changes.
action
Update pnpm to version 11.28.7 to benefit from security fixes and new features, and review breaking changes if using registry revisions.
release_signals
-Registry revisions are no longer supported. pnpm now fails with `ERR_PNPM_REGISTRY_REVISIONS_UNSUPPORTED` on registry metadata that selects a revision, on a `+rN` version specifier, and on a lockfile entry with a `revision` field. `pnpm update --patches` is removed.
release_signals
-Alpha.19 data is not migrated: startup refuses stores and databases created by alpha.19. A fresh hosted store and database are required, and the transparency log starts over.
-Configuration declaring `registries`, `defaultRegistry`, or `routes.public` is refused; registry configuration must be moved to a separate file and imported. Numerous configuration keys were renamed or regrouped, and `auth.users.file`, `auth.tokens.file`, and `log.type` were removed.
-`pnpr export` was removed. `pnpr import-htpasswd` no longer accepts `--target`. `PUT /-/pnpr/v0/admin/users/{id}` no longer creates accounts and returns 404 for unknown IDs.
-Publishing a new version is restricted to package owners and admins by default instead of any signed-in account; publishing an npm package makes its publisher its sole maintainer, requiring maintainers to be restored when republishing during migration.
-Registry names now have syntax and reserved-name constraints; nested ecosystem groups are refused, and renamed registry names require updating `/~<name>/` client URLs.
!A web login link alone can no longer sign anyone in.
!Credentials for a private upstream are no longer sent for package names outside that registry's `packages:` map.
!Tokens from password login and `npm token create` without an expiry now expire after 90 days by default, with a configurable maximum lifetime.
!Removed `auth.users.file` and `auth.tokens.file`; accounts and tokens are stored in the database.
!Removed `log.type`; pnpr always logs to stdout.
!Removed the `pnpr export` command.
!Removed the `--target` option from `pnpr import-htpasswd`.
+Registries are stored in the database, can be managed through the admin API, and support export, import, validation, and revision restoration.
+Package, crate, Python project, and image-repository owners can manage owners; publishing is restricted to owners and admins by default when no publish list is configured.
+Password-login tokens and tokens created without an expiry default to 90 days; `auth.tokens.defaultLifetime` and `auth.tokens.maxLifetime` configure token lifetimes.
+Added `POST /-/pnpr/v0/admin/users`, SCIM-user OIDC sign-in support, and expanded audit records with stable actor IDs and additional event types.
+Added `listen`, `publicUrl`, and Cloudflare CDN cache purging support.
migration_steps5 steps
01Back up the hosted store and databases, including local `tokens.db` and npm package maintainer lists.
02Point pnpr at an empty hosted store and empty database; recreate accounts and tokens, then update `auth.admins`, access lists, and team rosters because recreated accounts receive new IDs.
03Republish hosted packages and restore npm package maintainers afterward; republishing makes the publisher the sole maintainer. The new store starts a fresh transparency log that does not extend earlier checkpoints.
04Move registry configuration out of the main config into a separate file, apply the documented registry key and structure changes, then store it with `pnpr registries import`. Update client `/~<name>/` URLs if registry names change.
05Rename the documented configuration keys and adjust command usage, including replacing old `s3`/`database` and secret settings with their new forms; remove settings and commands that were removed.
!The bundled node-gyp no longer ships undici 6, which security scanners flag for CVE-2026-84947.
+With lockfile format v13, installs record local-directory package dependency specifiers, and frozen installs reject changed specifiers.
+Git dependency fragments now accept npm's `::` separator between parameters.
+Failed project-aware global runtime downloads provide clearer configuration guidance.
+pnpm recognizes Capawesome Cloud and RWX as CI environments.
migration_steps1 steps
01For remote resolution, shared build caches, or release notes, use a pnpr server newer than 0.1.0-alpha.19 that advertises the required capabilities under `pnpr.protocols`.
-Alpha.18 metadata and SQL auth databases are not migrated; startup refuses them and leaves them unchanged.
-The `backend` and `metadata` configuration blocks are no longer accepted; configure `database.url` instead.
-`pnpr oci-gc` and `pnpr verify --prune-orphans` are replaced by `pnpr gc`; `pnpr verify` no longer prunes, and its `--prune-orphans` and `--min-age` options are removed.
-Account references in `auth.admins`, access lists, and OIDC bindings must use account IDs rather than usernames; team entries must include `name` and `members`.
-Passwords must be at least eight characters, and npm publishes reject names disallowed for new npm packages, including uppercase letters and `@` in the package part.
!Fixes logging of credentials in malformed URLs whose `?` or `#` appears before `@`; such URLs are now redacted as `<scheme>://redacted`.
!User lookups now require authentication, and team names and rosters are visible only to team members and administrators.
!Authorization fails closed when team roster, managed access rule, or SCIM directory reads exceed five seconds.
!New accounts cannot use usernames that look like an existing username.
!The `backend` and `metadata` configuration blocks are removed in favor of `database.url`.
!`pnpr oci-gc` and `pnpr verify --prune-orphans` are replaced by `pnpr gc`.
!`pnpr verify` no longer removes orphaned blobs; its `--prune-orphans` and `--min-age` options are removed.
+Store package metadata in PostgreSQL or MySQL using `database.url`, alongside SQLite support.
+Store identical hosted archive bytes once per organization and ecosystem.
+Add `pnpr gc` to reclaim unreferenced archives across hosted npm, PyPI, Cargo, and OCI registries while serving.
+Add Python core-metadata support and `.metadata` caching so pip and uv can read dependency metadata without downloading whole wheels.
+Add OCI upload chunk-size advertisement through the `oci.chunkMaxBytes` setting.
migration_steps5 steps
01Back up alpha.18 databases, then delete pnpr's tables or point pnpr at new, empty databases.
02Point `storage` or the `s3:` prefix at a fresh location; hosted archives use a new layout, and a fresh local `storage` directory also creates a fresh SQLite metadata file.
03Replace `backend` and `metadata` blocks with `database.url`; pnpr refuses to start while either old block is present.
04Rename `auth.htpasswd` to `auth.users`; for local account-file setups, run `pnpr import-htpasswd --source <old htpasswd>` to import passwords. With other `database.url` values, recreate accounts.
05Recreate accounts and tokens, republish packages, and reconcile the SCIM directory with the identity provider; use `pnpr add-user <username>` to set a new password for accounts with passwords shorter than eight characters.
-Outside a workspace, `pnpm install`, `pnpm ci`, and `pnpm install-test` now fail with `ERR_PNPM_NO_PKG_MANIFEST` if no supported package manifest exists, instead of creating project files and `node_modules`.
!Fixed an offline-install error for tarballs missing from the store so it no longer prints credentials or tokens embedded in the tarball URL.
+Added `pnpm fund` to list or open dependency funding URLs, with JSON and workspace reporting options.
+The `loaded` node linker can build packages and use side-effects cache entries without requiring those packages to be listed in `nodeLinker.excluded`.
+Added the `projectScopedOptionalPeers` setting to scope missing optional peer dependencies to each project's own dependencies.
+Added experimental `lockfile.format: v13`, a JSON-like YAML lockfile format with package entries that record peer dependency versions.
+`pnpm store add` now recursively accepts directories of tarballs and is faster when adding many packages; installs and fetches also support storing dependencies for additional `supportedArchitectures` platforms.
migration_steps2 steps
01If a package's build must run in every project when using the `loaded` linker, add it to `sideEffectsCache.exclude`.
02If JavaScript source scanning cannot detect a package's computed filesystem imports, list that package in `nodeLinker.excluded`.
The `documents` metadata backend is removed; configurations using `metadata.backend` or `metadata.path` are refused.
-Existing document-backed stores are not imported and start with empty metadata; their packages must be republished.
-An S3-backed registry now requires a libSQL `metadata.url`; `migrate-storage` moves archives only and requires metadata to already be in that database.
-For registries configured with `tarballs: tar`, earlier versions published by an earlier pnpr are no longer served and must be republished; pnpr also refuses to start if a router without `tarballs: tar` lists such a registry as a source.
!When configured with signing keys, pnpr signs transparency-log checkpoints and registry acceptance statements for release records.
!Publishes with provenance statements that do not identify every archive by package URL and SHA-512 are rejected.
+Supports shared libSQL metadata databases, with optional local read replicas for multiple pnpr instances.
+Adds publication records, idempotent batch publishes, dist-tag history, and release notes for versions and publications.
+Supports staging package archives by integrity and publishing platform variants, including versions without an archive for every platform.
+Adds pnpr-specific package documents and release records, including per-version records, evidence, and optional signed transparency-log checkpoints and acceptance statements.
+Adds stricter archive/manifest validation and serves zstd-compressed tar archives for registries configured with `tarballs: tar`.
migration_steps3 steps
01Republish packages from document-backed stores after upgrading; pnpr does not import their existing metadata.
02For an S3-backed store, configure `metadata.url` with a libSQL database; ensure that database already contains metadata before using `migrate-storage`.
03Republish versions previously published to a `tarballs: tar` registry by an earlier pnpr.
-The package store layout has changed, and stores written by earlier pnpr versions are not read by this release.
-Removes `pnpr upgrade-storage`, `pnpr config-check`, several CLI flag aliases, and `PNPR_PACKUMENT_TTL_SECS`.
-Configuration keys now use camelCase; pnpr fails to start if it encounters old spellings such as `max_users`.
-Batch publishes now use `PUT /-/pnpr/v0/publish` or `PUT /npm/-/pnpr/v0/publish`; the former `PUT /-/pnpm/v1/publish` route is no longer served.
!Fixes memory exposure and allocation-handling vulnerabilities when processing zstd-compressed data (#17388).
!Changes signing to avoid arithmetic that could leak private keys through timing, covering shared artifacts, OCI registry tokens, and OIDC login state (RUSTSEC-2026-0387).
!Metrics are no longer served to anyone by default; they are served only when a `metrics` configuration block is present.
!Removes the legacy `pnpr upgrade-storage` and `pnpr config-check` commands.
!Removes `--packument-ttl-secs`, `--no-check-hashes`, `--min-age-secs`, `--max-age-secs`, and `PNPR_PACKUMENT_TTL_SECS`.
!Removes the legacy `PUT /-/pnpm/v1/publish` batch-publish endpoint.
+Serves Prometheus metrics at `/-/metrics` and `/metrics` only when a `metrics` configuration block is present, with optional bearer-token protection and a separate listen address.
+Adds package and file deletion routes without a trailing `/-rev/{rev}` segment, and accepts bare usernames on the user endpoints.
+Adds `backend.libsql.maxConnections` to limit concurrent auth database operations; the default is 10.
migration_steps4 steps
01Publish packages again into an empty store; this release does not read stores written by earlier pnpr versions.
02Replace the removed TTL flag or environment variable with `--packument-ttl` or `PNPR_PACKUMENT_TTL`, using a duration such as `5m` or `365d`.
03Rename configuration keys to camelCase, including `maxUsers`, `tokenEnv`, `maxAge`, `syncInterval`, and `backend.postgres`.
04For `pnpm -r publish --batch`, use pnpm 11.28.9 or 12.16.0 or later, as specified in the release notes.
-Filtered workspace installs now fail when the existing `node_modules` was installed with a different linker, hoist pattern, store, or virtual store. A whole-workspace `pnpm install` still recreates it.
-A dependency symlink that cannot be pointed to its intended target now causes the install to fail with an error naming the link, rather than retrying indefinitely.
!Fixed memory exposure and allocation-handling vulnerabilities in zstd-compressed data processing.
!Changed signing in pnpm and pnpr to avoid timing-leak-prone arithmetic that could expose private keys; this covers shared artifacts, OCI registry tokens, and OIDC login state (RUSTSEC-2026-0387).
+Added repeatable global `--env-file <path>` support; later files override earlier ones, existing environment variables are preserved, and loaded values are available to `.npmrc` interpolation and lifecycle scripts.
+Added configurable support for updating symlinked `pnpm-lock.yaml` files via `symlinkedLockfileTargetDirs` or `PNPM_CONFIG_SYMLINKED_LOCKFILE_TARGET_DIRS`.
+Added `pnpm setup --no-modify-path` to install pnpm without changing PATH-related shell, Windows registry, or GitHub Actions environment configuration.
migration_steps3 steps
01For `pnpm add`, `pnpm remove`, or `pnpm update` errors indicating that `node_modules` does not match current settings, run `pnpm install` to recreate it.
02To enable symlinked lockfile updates, list permitted target directories in the global `symlinkedLockfileTargetDirs` setting or set `PNPM_CONFIG_SYMLINKED_LOCKFILE_TARGET_DIRS`; this setting is ignored in `pnpm-workspace.yaml`.
03To use `pnpm setup` without automatic PATH changes, pass `--no-modify-path` and add the printed configuration lines yourself.
`artifacts.compilerCaches` and `pipeline.workspaces` are replaced with `artifacts.orgs`, which now manages permissions for signed artifacts, Cargo compilation cache, and pipeline run records.
-Configuration sections now strictly validate schema fields and reject unrecognized keys, unset environment variable references in secret fields, and retired top-level `uplinks` and `upstreams` blocks.
-Per-ecosystem validation rejects `teamsManagedBy: api` and package `unpublish` rules on Cargo and PyPI registries.
-pnpr no longer starts on a store in the earlier layout; requires `pnpr upgrade-storage` to convert the store to the new layout.
-Runs recorded by earlier versions are not listed in the new pipeline run organization structure.
!pnpr now supports npm audit endpoints for security advisories and audits.
!Token authentication now includes expiry and CIDR restrictions.
!Package write requests now check permissions before buffering large request bodies.
!Login endpoints enforce rate limits.
!pnpr now resolves client IP addresses through trusted reverse proxies for better security logging and enforcement.
!`artifacts.compilerCaches` and `pipeline.workspaces` are deprecated in favor of `artifacts.orgs`.
!Top-level `uplinks` and `upstreams` blocks are retired; configure upstreams in `registries` instead.
+pnpr now serves every ecosystem under its own URL prefix, including npm, Cargo, Python, and container image registries.
+Added support for tar registries, zstd metadata and tarball compression.
+Introduced npm audit and provenance endpoints.
+Added Prometheus metrics and `pnpr` maintenance commands.
+Supports token creation with `--read-only`, CIDR restrictions, expiry, and token naming.
migration_steps3 steps
01Back up the store and convert it with `pnpr upgrade-storage` to the new layout.
02Update configurations to use `artifacts.orgs` instead of `artifacts.compilerCaches` and `pipeline.workspaces`.
03Move upstream configurations from `uplinks` and `upstreams` to `registries`.
pnpm now fails with `ERR_PNPM_REGISTRY_NAME_MISMATCH` if a registry returns metadata for a package other than the one requested.
!pnpm now applies `trustPolicy` to the pnpm version a project pins in `packageManager` or `devEngines.packageManager`.
!Added the `maxTarballUnpackedSize` setting to limit unpacked package size to 4 GiB by default.
+Added the `maxTarballUnpackedSize` setting to cap unpacked package size.
+pnpm now applies `trustPolicy` to the pnpm version a project pins in `packageManager` or `devEngines.packageManager`.
+`minimumReleaseAgeExcludePrune` and `trustPolicyExcludePrune` now keep exclusions for resolved configuration dependencies and their transitive dependencies.