●Change8

Migrating to pnpm v11.10.0

Version v11.10.0 introduces 5 breaking changes. This guide details how to update your code.

Released: 7/4/2026

5
Breaking Changes
2
Migration Steps
12
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

pnpm config (_auth setting)pnpm_config__auth (environment variable)PNPM_CONFIG__AUTH (environment variable)pnpm issues commandpnpm prefix commandpnpm self-updatepackageManager version-switchingpnpm up -rpnpm packpnpm publishpnpm add -g pnpmpnpm audit --fix (implied via preferredVersions logic)

Breaking Changes

●Issue #1

The method for configuring registry authentication via environment variables has changed significantly with the introduction of the `_auth` setting.

✓Solution

Use the new structured environment variable `pnpm_config__auth` (or `PNPM_CONFIG__AUTH`) containing a JSON object keyed by registry URL, instead of the old format like `pnpm_config_//host/:_authToken=…`. Example: `export pnpm_config__auth='{"https://registry.npmjs.org":{"@":{"authToken":"npm-token"}}}'`.

●Issue #2

The `_auth` setting is now honored ONLY from the environment variable (`pnpm_config__auth`) and the global `config.yaml`. It is ignored in project-level configuration (`pnpm-workspace.yaml` or `.npmrc`).

✓Solution

If registry authentication needs to be controlled by repository configuration, it must now be set via the environment variable or global config, as project-level configuration cannot supply registry auth tokens.

●Issue #3

The deprecated `basicAuth` / `username` + `password` credential forms are intentionally not supported within the new structured `_auth` setting.

✓Solution

Use the supported `authToken` field within the `_auth` configuration.

●Issue #4

pnpm now rejects `jsr:` specifiers and named-registry specifiers (like `gh:`) if the package name part does not conform to valid npm package naming rules (checked via `validate-npm-package-name`).

✓Solution

Ensure all package names used in `jsr:` or named-registry specifiers are valid npm package names. Malformed names will now result in an error (`ERR_PNPM_INVALID_JSR_PACKAGE_NAME` or `ERR_PNPM_INVALID_NAMED_REGISTRY_PACKAGE_NAME`) instead of silent transformation.

●Issue #5

When resolving through a pnpr install-accelerator server, pnpm no longer forwards its own upstream registry credentials in the resolve request.

✓Solution

Ensure the pnpr server is configured with appropriate upstream credential aliases for private dependency resolution, as client tokens are no longer passed upstream.

Migration Steps

  1. 1
    If you were setting registry authentication via environment variables using the old format (e.g., `pnpm_config_//host/:_authToken=…`), update your CI/environment setup to use the new structured JSON format via `pnpm_config__auth` or `PNPM_CONFIG__AUTH`.
  2. 2
    If you rely on project-level configuration (`.npmrc` or `pnpm-workspace.yaml`) to set registry authentication tokens, move those settings to the global `config.yaml` or environment variables, as project-level auth configuration is now ignored.

Release Summary

This release introduces a robust, structured configuration method for registry authentication via environment variables and global config, fixes several bugs related to package updates and global package management, and improves compatibility with the new Rust-based pnpm executable.

Need More Details?

View the full release notes and all changes for pnpm v11.10.0.

View Full Changelog