●Change8

Migrating to pnpm v11.0.0-alpha.16

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

Released: 3/15/2026

21
Breaking Changes
9
Migration Steps
18
Affected Symbols

⚠️ Check Your Code

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

`pnpm config get``pnpm config list`Global package installation mechanism`patchedDependencies` lockfile format`pnpm link``pnpm publish` OTP handling`pnpm init` default type`onlyBuiltDependencies``onlyBuiltDependenciesFile``neverBuiltDependencies``ignoredBuiltDependencies``allowNonAppliedPatches``ignorePatchFailures``pnpm server``useNodeVersion``executionEnv.nodeVersion``hooks.fetchers``fetchers` field in `pnpmfile`

Breaking Changes

●Issue #1

The `pnpm config get` command (without `--json`) now outputs JSON for objects/arrays and raw strings for primitives, instead of INI formatted text. Use `pnpm config get --json` if you require JSON output for all types.

●Issue #2

The `pnpm config list` command now outputs a JSON object instead of INI formatted text.

●Issue #3

Auth-related settings are hidden when running `pnpm config list` or `pnpm config get` (without arguments).

●Issue #4

Top-level keys in `pnpm config list` and `pnpm config get` (without arguments) are now shown as camelCase, except for keys starting with `@` or `//`.

●Issue #5

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

●Issue #6

Workspace project specific `.npmrc` files are replaced by the `packageConfigs` field in `pnpm-workspace.yaml`.

●Issue #7

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

●Issue #8

This package is now pure ESM; ensure your environment supports ESM.

●Issue #9

Node.js v18, v19, v20, and v21 support is discontinued. Upgrade to a supported Node.js version.

●Issue #10

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

●Issue #11

Deprecated build dependency settings (`onlyBuiltDependencies`, `onlyBuiltDependenciesFile`, `neverBuiltDependencies`, and `ignoredBuiltDependencies`) are removed. Use the `allowBuilds` setting 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 is removed.

●Issue #15

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

●Issue #16

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

●Issue #17

The default value for the `type` field in `package.json` initialized by `pnpm init` is changed to `module`.

●Issue #18

Lowercase options for `pnpm add` have new meanings: `-p` is now an alias for `--save-prod` (was `--parseable`), and `-d` is now an alias for `--save-dev` (was `--loglevel=info`).

●Issue #19

`pnpm link <pkg-name>` no longer resolves packages from the global store; only relative or absolute paths are accepted (e.g., use `pnpm link ./foo`).

●Issue #20

`pnpm link --global` is removed. Use `pnpm add -g .` to register a local package's bins globally.

●Issue #21

`pnpm link` (no arguments) is removed. Use `pnpm link <dir>` with an explicit directory.

Migration Steps

  1. 1
    If you relied on INI output from `pnpm config get` (without `--json`), switch to using `pnpm config get --json` or update scripts to handle JSON output.
  2. 2
    Update configuration logic that relied on `.npmrc` files in workspace projects to use the `packageConfigs` field in `pnpm-workspace.yaml`.
  3. 3
    Replace usage of deprecated build dependency settings (`onlyBuiltDependencies`, etc.) with the `allowBuilds` map in configuration.
  4. 4
    If you used `pnpm link <pkg-name>` where `<pkg-name>` referred to a globally installed package, change it to use a path, e.g., `pnpm link ./foo`.
  5. 5
    If you used `pnpm link --global`, switch to using `pnpm add -g .`.
  6. 6
    If you relied on `pnpm link` without arguments, use `pnpm link <dir>` explicitly.
  7. 7
    Update scripts that relied on `NPM_CONFIG_OTP` for publishing to use `PNPM_CONFIG_OTP`.
  8. 8
    Ensure your Node.js version is supported (not v18, v19, v20, or v21).
  9. 9
    If using the standalone executable, ensure glibc version is 2.27 or higher.

Release Summary

This release introduces major architectural changes to the pnpm store, moving to SQLite for metadata indexing and isolating global package installations for better stability. Configuration commands and build dependency handling have also been significantly overhauled, and support for older Node.js versions has been dropped.

Need More Details?

View the full release notes and all changes for pnpm v11.0.0-alpha.16.

View Full Changelog