1---
2name: pnpm-overrides
3description: Force specific versions of dependencies including transitive dependencies
4---
5 
6# pnpm Overrides
7 
8Overrides let you force specific versions of packages, including transitive dependencies. Useful for fixing security vulnerabilities or compatibility issues.
9 
10## Basic Syntax
11 
12Define overrides in `pnpm-workspace.yaml` (recommended) or `package.json`:
13 
14### In pnpm-workspace.yaml (Recommended)
15 
16```yaml
17packages:
18  - 'packages/*'
19 
20overrides:
21  # Override all versions of a package
22  lodash: ^4.17.21
23  
24  # Override specific version range
25  "foo@^1.0.0": ^1.2.3
26  
27  # Override nested dependency
28  "express>cookie": ^0.6.0
29  
30  # Override to different package
31  "underscore": "npm:lodash@^4.17.21"
32```
33 
34### In package.json
35 
36```json
37{
38  "pnpm": {
39    "overrides": {
40      "lodash": "^4.17.21",
41      "foo@^1.0.0": "^1.2.3",
42      "bar@^2.0.0>qux": "^1.0.0"
43    }
44  }
45}
46```
47 
48## Override Patterns
49 
50### Override all instances
51```yaml
52overrides:
53  lodash: ^4.17.21
54```
55Forces all lodash installations to use ^4.17.21.
56 
57### Override specific parent version
58```yaml
59overrides:
60  "foo@^1.0.0": ^1.2.3
61```
62Only override foo when the requested version matches ^1.0.0.
63 
64### Override nested dependency
65```yaml
66overrides:
67  "express>cookie": ^0.6.0
68  "[email protected]>bar@^2.0.0>qux": ^1.0.0
69```
70Override cookie only when it's a dependency of express.
71 
72### Replace with different package
73```yaml
74overrides:
75  # Replace underscore with lodash
76  "underscore": "npm:lodash@^4.17.21"
77  
78  # Use local file
79  "some-pkg": "file:./local-pkg"
80  
81  # Use git
82  "some-pkg": "github:user/repo#commit"
83```
84 
85### Remove a dependency
86```yaml
87overrides:
88  "unwanted-pkg": "-"
89```
90The `-` removes the package entirely.
91 
92## Common Use Cases
93 
94### Security Fix
95 
96Force patched version of vulnerable package:
97 
98```yaml
99overrides:
100  # Fix CVE in transitive dependency
101  "minimist": "^1.2.6"
102  "json5": "^2.2.3"
103```
104 
105### Deduplicate Dependencies
106 
107Force single version when multiple are installed:
108 
109```yaml
110overrides:
111  "react": "^18.2.0"
112  "react-dom": "^18.2.0"
113```
114 
115### Fix Peer Dependency Issues
116 
117```yaml
118overrides:
119  "@types/react": "^18.2.0"
120```
121 
122### Replace Deprecated Package
123 
124```yaml
125overrides:
126  "request": "npm:@cypress/request@^3.0.0"
127```
128 
129## Hooks Alternative
130 
131For more complex scenarios, use `.pnpmfile.cjs`:
132 
133```js
134// .pnpmfile.cjs
135function readPackage(pkg, context) {
136  // Override dependency version
137  if (pkg.dependencies?.lodash) {
138    pkg.dependencies.lodash = '^4.17.21'
139  }
140  
141  // Add missing peer dependency
142  if (pkg.name === 'some-package') {
143    pkg.peerDependencies = {
144      ...pkg.peerDependencies,
145      react: '*'
146    }
147  }
148  
149  return pkg
150}
151 
152module.exports = {
153  hooks: {
154    readPackage
155  }
156}
157```
158 
159## Overrides vs Catalogs
160 
161| Feature | Overrides | Catalogs |
162|---------|-----------|----------|
163| Affects | All dependencies (including transitive) | Direct dependencies only |
164| Usage | Automatic | Explicit `catalog:` reference |
165| Purpose | Force versions, fix issues | Version management |
166| Granularity | Can target specific parents | Package-wide only |
167 
168## Debugging
169 
170Check which version is resolved:
171 
172```bash
173# See resolved versions
174pnpm why lodash
175 
176# List all versions
177pnpm list lodash --depth=Infinity
178```
179 
180<!-- 
181Source references:
182- https://pnpm.io/package_json#pnpmoverrides
183- https://pnpm.io/pnpmfile
184-->
185