Migrating to pnpm v11.0.0-beta.8

Version v11.0.0-beta.8 introduces 11 breaking changes. This guide details how to update your code.

Released: 4/8/2026

Breaking Changes

Migration Steps

Affected Symbols

⚠️ Check Your Code

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

pnpm config getpnpm config listpnpm add -gpnpm dlxpnpm install -gnpm_config_* environment variablespnpm_config_* environment variablesonlyBuiltDependenciesonlyBuiltDependenciesFileneverBuiltDependenciesignoredBuiltDependenciesignoreDepScriptsallowBuildspatchedDependencies (lockfile format)

Breaking Changes

●Issue #1

{"fix":"Update scripts to use `pnpm_config_*` environment variables instead of `npm_config_*` if configuration values are needed.","breaking_change":"pnpm no longer populates `npm_config_*` environment variables from the pnpm config during lifecycle scripts. Only well-known `npm_*` env vars are set."}

✓Solution

Update scripts to use `pnpm_config_*` environment variables instead of `npm_config_*` if configuration values are needed.

●Issue #2

{"fix":"Use `pnpm config get --json` or `pnpm config list --json` if INI format is strictly required, or update scripts to parse JSON output.","breaking_change":"pnpm config get (without --json) and pnpm config list no longer print INI formatted text; they now print JSON or raw strings/values."}

✓Solution

Use `pnpm config get --json` or `pnpm config list --json` if INI format is strictly required, or update scripts to parse JSON output.

●Issue #3

{"fix":"If specific non-camelCase or auth keys were relied upon in scripting, update selectors or use `--json`.","breaking_change":"pnpm config get/list now hide auth-related settings and show top-level keys as camelCase (except keys starting with @ or //)."}

✓Solution

If specific non-camelCase or auth keys were relied upon in scripting, update selectors or use `--json`.

●Issue #4

{"fix":"Ensure configuration keys in `pnpm-workspace.yaml` adhere to camelCase convention for non-exception keys.","breaking_change":"pnpm config get/list no longer load non camelCase options from the workspace manifest (`pnpm-workspace.yaml`)."}

✓Solution

Ensure configuration keys in `pnpm-workspace.yaml` adhere to camelCase convention for non-exception keys.

●Issue #5

{"fix":"Move configuration settings like `hoistPattern`, `nodeLinker`, `shamefullyHoist`, etc., from `.npmrc` files to `pnpm-workspace.yaml` or `~/.config/pnpm/config.yaml`.","breaking_change":"pnpm no longer reads most settings from `.npmrc` files. Only auth and registry settings are read from `.npmrc` files."}

✓Solution

Move configuration settings like `hoistPattern`, `nodeLinker`, `shamefullyHoist`, etc., from `.npmrc` files to `pnpm-workspace.yaml` or `~/.config/pnpm/config.yaml`.

●Issue #6

{"fix":"Use `pnpm_config_*` environment variables (e.g., `pnpm_config_registry`) instead of `npm_config_*`.","breaking_change":"pnpm no longer reads `npm_config_*` environment variables."}

✓Solution

Use `pnpm_config_*` environment variables (e.g., `pnpm_config_registry`) instead of `npm_config_*`.

●Issue #7

{"fix":"Use the new `allowBuilds` setting, which is a map where keys are package name patterns and values are booleans (`true` to allow build scripts, `false` to deny).","breaking_change":"Deprecated build dependency settings (`onlyBuiltDependencies`, `onlyBuiltDependenciesFile`, `neverBuiltDependencies`, `ignoredBuiltDependencies`, and `ignoreDepScripts`) are removed."}

✓Solution

Use the new `allowBuilds` setting, which is a map where keys are package name patterns and values are booleans (`true` to allow build scripts, `false` to deny).

●Issue #8

{"fix":"If necessary, disable this feature by setting `enableGlobalVirtualStore: false` in configuration.","breaking_change":"Global installs (`pnpm add -g pkg`) and `pnpm dlx` now use the global virtual store by default, storing packages at `{storeDir}/links`."}

✓Solution

If necessary, disable this feature by setting `enableGlobalVirtualStore: false` in configuration.

●Issue #9

{"fix":"Use `pnpm add -g <pkg>` instead to install global packages.","breaking_change":"`pnpm install -g` (with no arguments) is no longer supported."}

✓Solution

Use `pnpm add -g <pkg>` instead to install global packages.

●Issue #10

{"fix":"Upgrade Node.js version to v22 or later.","breaking_change":"Node.js v18, 19, 20, and 21 support discontinued."}

✓Solution

Upgrade Node.js version to v22 or later.

●Issue #11

{"fix":"Migrate project-specific configurations from `.npmrc` files to the `packageConfigs` array/object structure within `pnpm-workspace.yaml`.","breaking_change":"Workspace project specific `.npmrc` files are replaced by the `packageConfigs` setting in `pnpm-workspace.yaml`."}

✓Solution

Migrate project-specific configurations from `.npmrc` files to the `packageConfigs` array/object structure within `pnpm-workspace.yaml`.

Migration Steps

1
If relying on `npm_config_*` environment variables in lifecycle scripts, change them to use `pnpm_config_*` variables.
2
If scripts relied on INI formatting from `pnpm config get` or `pnpm config list`, update them to parse JSON output or use the `--json` flag.
3
Ensure configuration settings previously in `.npmrc` (like `hoistPattern`, `nodeLinker`) are moved to `pnpm-workspace.yaml` or global config.
4
Replace deprecated build dependency settings (`onlyBuiltDependencies`, etc.) with the `allowBuilds` setting in configuration.
5
If using project-specific `.npmrc` files for configuration, migrate those settings into the `packageConfigs` section of `pnpm-workspace.yaml`.
6
If you need to opt out of the 1-day minimum release age protection, set `minimumReleaseAge: 0` in `pnpm-workspace.yaml`.

Release Summary

This release introduces major architectural changes, including migrating the package index store to SQLite and isolating global package installations for better stability. Configuration handling has been significantly updated, moving most settings away from .npmrc files to pnpm-workspace.yaml and standardizing CLI output formats.

Need More Details?

View the full release notes and all changes for pnpm v11.0.0-beta.8.

View Full Changelog