●Change8

Migrating to pnpm v11.0.0-beta.1

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

Released: 3/21/2026

20
Breaking Changes
12
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 (packageConfigs)

Breaking Changes

●Issue #1

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

●Issue #2

Node.js v18, 19, 20, and 21 support has been discontinued. Upgrade your Node.js version.

●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 `pnpm config get --json`.

●Issue #4

pnpm config list now prints a JSON object instead of INI formatted text. If you relied on INI output, this has changed.

●Issue #5

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

●Issue #6

pnpm config list and pnpm config get (without argument) now show top-level keys as camelCase, except for keys starting with @ or //.

●Issue #7

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

●Issue #8

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

●Issue #9

Replaced workspace project specific `.npmrc` with `packageConfigs` in `pnpm-workspace.yaml`. You must migrate configuration settings from `.npmrc` files in project directories to the `packageConfigs` field in `pnpm-workspace.yaml`.

●Issue #10

The lockfile format for `patchedDependencies` changed from `Record<string, { path: string, hash: string }>` to `Record<string, string>`. Existing lockfiles are migrated automatically.

●Issue #11

The deprecated build dependency settings (`onlyBuiltDependencies`, `onlyBuiltDependenciesFile`, `neverBuiltDependencies`, and `ignoredBuiltDependencies`) have been removed. Use the `allowBuilds` setting in configuration instead.

●Issue #12

The deprecated `allowNonAppliedPatches` is completely removed in favor of `allowUnusedPatches`.

●Issue #13

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

●Issue #14

The `pnpm server` command has been removed.

●Issue #15

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

●Issue #16

Support for `hooks.fetchers` has been removed. Use the new API via the `fetchers` field of `pnpmfile`.

●Issue #17

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

●Issue #18

Lowercase options for `pnpm add` are now aliases: `-p` is now `--save-prod` (was `--parseable`), and `-d` is now `--save-dev` (was `--loglevel=info`).

●Issue #19

The One-time Password feature for `pnpm publish` now reads from `PNPM_CONFIG_OTP` instead of `NPM_CONFIG_OTP`.

●Issue #20

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`), switch to using `pnpm config get --json`.
  2. 2
    Migrate configuration settings defined in project-specific `.npmrc` files into the `packageConfigs` field within your root `pnpm-workspace.yaml`.
  3. 3
    Replace usage of deprecated build dependency settings (`onlyBuiltDependencies`, etc.) with the `allowBuilds` setting in your configuration, mapping package patterns to `true` (allowed to build) or `false` (denied build).
  4. 4
    If you used `allowNonAppliedPatches`, rename this configuration to `allowUnusedPatches`.
  5. 5
    Remove any usage of the `ignorePatchFailures` setting.
  6. 6
    If you used `useNodeVersion` or `executionEnv.nodeVersion` fields, replace them with `devEngines.runtime` or `engines.runtime`.
  7. 7
    If you used `hooks.fetchers` in `pnpmfile`, migrate to the new API using the `fetchers` field in `pnpmfile`.
  8. 8
    If you relied on settings in the `pnpm` field of `package.json`, move them to `pnpm-workspace.yaml`.
  9. 9
    If you relied on the old behavior of `pnpm add -p` (as `--parseable`) or `pnpm add -d` (as `--loglevel=info`), update scripts to use the new aliases (`--save-prod` and `--save-dev` respectively) or the full flags.
  10. 10
    For publishing requiring OTP, use the `PNPM_CONFIG_OTP` environment variable or the `--otp` flag instead of `NPM_CONFIG_OTP`.
  11. 11
    If you were using global installs and relied on them being in project-local `.pnpm` directories, note that they now use the global virtual store at `{storeDir}/links` (unless `enableGlobalVirtualStore: false` is set).
  12. 12
    If you used `pnpm install -g` without arguments, change this to `pnpm add -g <pkg>`.

Release Summary

This major release introduces significant architectural changes to the content-addressable store using SQLite and optimizes metadata storage, while isolating global package installations for better stability. Configuration handling has been overhauled, moving project-specific settings out of `.npmrc` and standardizing CLI output formats.

Need More Details?

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

View Full Changelog