Pnpm

name: pnpm-overrides description: Force specific versions of dependencies including transitive dependencies

pnpm Overrides

Overrides let you force specific versions of packages, including transitive dependencies. Useful for fixing security vulnerabilities or compatibility issues.

Basic Syntax

Define overrides in pnpm-workspace.yaml. They can only be set at the root of the project.

The pnpm.overrides field in package.json is no longer read (pnpm no longer reads any settings from package.json#pnpm). Move overrides to pnpm-workspace.yaml.

packages:
  - 'packages/*'

overrides:
  # Override all versions of a package
  lodash: ^4.17.21

  # Override specific version range
  "foo@^1.0.0": ^1.2.3

  # Override nested dependency (only zoo inside qar@1)
  "qar@1>zoo": "2"

  # Override to different package
  "underscore": "npm:lodash@^4.17.21"

  # Reference a catalog so the version stays in sync
  "react": "catalog:"

Override Patterns

Override all instances

overrides:
  lodash: ^4.17.21

Forces all lodash installations to use ^4.17.21.

Override specific parent version

overrides:
  "foo@^1.0.0": ^1.2.3

Only override foo when the requested version matches ^1.0.0.

Override nested dependency

overrides:
  "express>cookie": ^0.6.0
  "[email protected]>bar@^2.0.0>qux": ^1.0.0

Override cookie only when it's a dependency of express.

Replace with different package

overrides:
  # Replace underscore with lodash
  "underscore": "npm:lodash@^4.17.21"
  
  # Use local file
  "some-pkg": "file:./local-pkg"
  
  # Use git
  "some-pkg": "github:user/repo#commit"

Remove a dependency

overrides:
  "unwanted-pkg": "-"
  "[email protected]>bar": "-"   # great for skipping unused optionalDependencies

The - removes the package entirely.

Override peer dependencies

Overrides also apply to peerDependencies:

overrides:
  "react-dom>react": "18.1.0"

Without a selector, an override applies to dependencies, devDependencies, optionalDependencies, and peerDependencies. Use the :peer suffix to target only peerDependencies:

overrides:
  "react-dom>react:peer": "^18.0.0 || ^19.0.0"
  "@babel/*:peer": "*"

• Ranges, workspace:, and catalog: replace the peer range.

• Non-range specifiers (link:, file:, npm:) leave peerDependencies unchanged (an untyped "foo": "file:./foo.tgz" replaces foo in dependencies only).

• - removes the peer dependency and its peerDependenciesMeta entry.

• To turn a peer into a direct dep: add it under packageExtensions.<pkg>.dependencies and override "<pkg>>dep:peer": "-".

Dependency-type selectors and wildcards

Append :prod (only dependencies), :optional, or :peer to the target to restrict the group. Both parent and target selectors support * on package names:

overrides:
  "foo:prod": "^2.0.0"
  "@esbuild/*:optional": "-"   # also removes duplicate declaration from dependencies

Convergence overrides

An empty range selector "pkg@" rewrites an edge only when the pinned version satisfies the range that edge declares, so compatible consumers converge without forcing an incompatible one:

overrides:
  "form-data@": 4.0.6   # ^4.0.5 edges -> 4.0.6; ^3.0.0 edges untouched

Value must be an exact version (or a catalog: entry resolving to one), else ERR_PNPM_INVALID_CONVERGENCE_OVERRIDE. Only plain semver edges participate. Cannot combine with a parent selector ("parent>pkg@" rejected). A regular override wins for the same edge. pnpm warns when the override is stale.

Common Use Cases

Security Fix

Force patched version of vulnerable package:

overrides:
  # Fix CVE in transitive dependency
  "minimist": "^1.2.6"
  "json5": "^2.2.3"

Deduplicate Dependencies

Force single version when multiple are installed:

overrides:
  "react": "^18.2.0"
  "react-dom": "^18.2.0"

Fix Peer Dependency Issues

overrides:
  "@types/react": "^18.2.0"

Replace Deprecated Package

overrides:
  "request": "npm:@cypress/request@^3.0.0"

Hooks Alternative

For more complex scenarios, use .pnpmfile.mjs:

function readPackage(pkg, context) {
  // Override dependency version
  if (pkg.dependencies?.lodash) {
    pkg.dependencies.lodash = '^4.17.21'
  }

  // Add missing peer dependency
  if (pkg.name === 'some-package') {
    pkg.peerDependencies = {
      ...pkg.peerDependencies,
      react: '*'
    }
  }

  return pkg
}

export const hooks = {
  readPackage
}

Or extend a manifest declaratively with packageExtensions (no JS needed):

packageExtensions:
  react-redux:
    peerDependencies:
      react-dom: '*'

Overrides vs Catalogs

Debugging

Check which version is resolved:

# See resolved versions
pnpm why lodash

# List all versions
pnpm list lodash --depth=Infinity

<!-- Source references: - https://pnpm.io/settings#overrides - https://pnpm.io/settings#packageextensions - https://pnpm.io/pnpmfile -->