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 (recommended) or package.json:

In pnpm-workspace.yaml (Recommended)

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
  "express>cookie": ^0.6.0
  
  # Override to different package
  "underscore": "npm:lodash@^4.17.21"

In package.json

{
  "pnpm": {
    "overrides": {
      "lodash": "^4.17.21",
      "foo@^1.0.0": "^1.2.3",
      "bar@^2.0.0>qux": "^1.0.0"
    }
  }
}

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": "-"

The - removes the package entirely.

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.cjs:

// .pnpmfile.cjs
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
}

module.exports = {
  hooks: {
    readPackage
  }
}

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/package_json#pnpmoverrides
• https://pnpm.io/pnpmfile

-->