●Change8

Migrating to pnpm v11.0.0-beta.3

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

Released: 3/26/2026

21
Breaking Changes
8
Migration Steps
32
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 remove -gpnpm update -gpnpm list -gpnpm install -gpatchedDependencies (lockfile format)onlyBuiltDependenciesonlyBuiltDependenciesFileneverBuiltDependenciesignoredBuiltDependenciesallowBuildsallowNonAppliedPatchesallowUnusedPatchesignorePatchFailurespnpm serveruseNodeVersionexecutionEnv.nodeVersiondevEngines.runtimeengines.runtimehooks.fetchersfetchers (pnpmfile field)pnpm init (default type)pnpm add -ppnpm add -dpnpm publishNPM_CONFIG_OTPPNPM_CONFIG_OTPpnpm field (package.json)pnpm-workspace.yaml

Breaking Changes

●Issue #1

The standalone exe version of pnpm requires at least glibc 2.27.

●Issue #2

Node.js v18, v19, v20, and v21 support has been discontinued. Users must upgrade Node.js.

●Issue #3

pnpm config get (without --json) no longer prints INI formatted text; it now prints JSON for objects/arrays and raw strings for primitives. If you relied on INI output, use --json.

●Issue #4

pnpm config get <array> now prints a JSON array instead of INI format.

●Issue #5

pnpm config list now prints a JSON object instead of INI formatted text.

●Issue #6

pnpm config list and pnpm config get (without argument) now hide auth-related settings.

●Issue #7

pnpm config list and pnpm config get (without argument) now show top-level keys as camelCase (unless they start with @ or //).

●Issue #8

pnpm config get and pnpm config list no longer load non camelCase options from the workspace manifest (pnpm-workspace.yaml).

●Issue #9

pnpm no longer loads non-auth and non-registry settings from rc files. Other settings must be defined in pnpm-workspace.yaml.

●Issue #10

Workspace project specific .npmrc files are replaced by the packageConfigs field in pnpm-workspace.yaml. Migrate settings from .npmrc files into packageConfigs.

●Issue #11

The lockfile format for patchedDependencies is simplified from Record<string, { path: string, hash: string }> to Record<string, string> (selector to hash). Existing lockfiles are migrated automatically.

●Issue #12

The deprecated build dependency settings: onlyBuiltDependencies, onlyBuiltDependenciesFile, neverBuiltDependencies, and ignoredBuiltDependencies are removed. Use the allowBuilds setting instead.

●Issue #13

The deprecated allowNonAppliedPatches is completely removed in favor of allowUnusedPatches.

●Issue #14

ignorePatchFailures is removed; all patch application failures will now throw an error.

●Issue #15

The pnpm server command has been removed.

●Issue #16

Support for the useNodeVersion and executionEnv.nodeVersion fields has been removed. Use devEngines.runtime and engines.runtime instead.

●Issue #17

Support for hooks.fetchers has been removed. Use the fetchers field of pnpmfile for custom fetchers and resolvers.

●Issue #18

The default value of the type field in package.json initialized by pnpm init is now "module".

●Issue #19

pnpm add command aliases changed: -p is now an alias for --save-prod (was --parseable), and -d is now an alias for --save-dev (was --loglevel=info).

●Issue #20

pnpm publish now reads OTP from PNPM_CONFIG_OTP instead of NPM_CONFIG_OTP.

●Issue #21

pnpm no longer reads settings from the pnpm field of package.json. Settings must be defined in pnpm-workspace.yaml.

Migration Steps

  1. 1
    If you relied on INI output from `pnpm config get` without `--json`, update scripts to use `--json` or handle JSON output.
  2. 2
    Migrate configuration settings from the `pnpm` field in `package.json` to `pnpm-workspace.yaml`.
  3. 3
    Replace deprecated build dependency settings (`onlyBuiltDependencies`, etc.) with the `allowBuilds` map in configuration files.
  4. 4
    Replace usage of deprecated `allowNonAppliedPatches` with `allowUnusedPatches`.
  5. 5
    If you relied on undocumented features of `pnpm publish` that used `npm publish` internally, consider using the workaround: `pnpm pack && npm publish *.tgz`.
  6. 6
    Update scripts that relied on the old aliases for `pnpm add`: `-p` is now `--save-prod`, `-d` is now `--save-dev`.
  7. 7
    If using global packages, note that they are now isolated and stored in `{pnpmHomeDir}/global/v11/{hash}/`. If you need the old behavior, set `enableGlobalVirtualStore: false`.
  8. 8
    If you were using `.npmrc` files per workspace project, migrate those settings to the `packageConfigs` field in `pnpm-workspace.yaml`.

Release Summary

This major release introduces significant architectural changes to the content-addressable store using SQLite and optimizes metadata storage, alongside isolating global package installations for better stability. Configuration handling has been overhauled, moving away from rc files and project-specific .npmrcs in favor of centralized workspace configuration.

Need More Details?

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

View Full Changelog