●Change8

Migrating to pnpm v11.5.3

Version v11.5.3 introduces 3 breaking changes. This guide details how to update your code.

Released: 6/10/2026

3
Breaking Changes
3
Migration Steps
5
Affected Symbols

⚠️ Check Your Code

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

pnpm config get globalconfigpnpm installpnpm dedupe --checkpnpm stage downloadallowBuilds

Breaking Changes

●Issue #1

Environment variables are no longer expanded in repository-controlled registry/proxy request destinations, registry credential values from .npmrc, and workspace registry URLs from pnpm-workspace.yaml. Users must move dynamic registry URL and token configuration to trusted user, global, CLI, or environment config.

●Issue #2

Lockfile verification now rejects lockfiles where a registry-style dependency path (name@semver) is backed by a git, directory, or git-hosted tarball resolution (ERR_PNPM_RESOLUTION_SHAPE_MISMATCH). This enforces that dependency paths reliably reflect artifact identity before lifecycle scripts run.

●Issue #3

Reserved manifest bin names ("", ".", "..", and scoped forms like @scope/..) are now rejected when resolving package bins. Previously, these could lead to recursive deletion of the global bin directory or its parent during global operations.

Migration Steps

  1. 1
    If using dynamic registry URLs or tokens configured in .npmrc or pnpm-workspace.yaml, move this configuration to trusted user, global, CLI, or environment configuration.
  2. 2
    If using "$" syntax in overrides (e.g., "react": "$react"), update to use the catalog protocol instead (e.g., "react": "catalog:react").
  3. 3
    If relying on repository-controlled inputs to select package manager engines or Node.js runtimes, ensure that the lockfile/manifest integrity matches the expected signature, or the command will fail if verification cannot be completed.

Release Summary

This patch release introduces significant security enhancements by verifying signatures for package manager binaries and downloaded Node.js runtimes, alongside fixes for configuration expansion, lockfile generation, and CLI flag parsing.

Need More Details?

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

View Full Changelog