1---
2name: pnpm-performance-optimization
3description: Tips and tricks for faster installs and better performance
4---
5 
6# pnpm Performance Optimization
7 
8pnpm is fast by default, but these optimizations can make it even faster.
9 
10## Install Optimizations
11 
12### Use Frozen Lockfile
13 
14Skip resolution when lockfile exists:
15 
16```bash
17pnpm install --frozen-lockfile
18```
19 
20This is faster because pnpm skips the resolution phase entirely.
21 
22### Prefer Offline Mode
23 
24Use cached packages when available:
25 
26```bash
27pnpm install --prefer-offline
28```
29 
30Or configure globally:
31```ini
32# .npmrc
33prefer-offline=true
34```
35 
36### Skip Optional Dependencies
37 
38If you don't need optional deps:
39 
40```bash
41pnpm install --no-optional
42```
43 
44### Skip Scripts
45 
46For CI or when scripts aren't needed:
47 
48```bash
49pnpm install --ignore-scripts
50```
51 
52**Caution:** Some packages require postinstall scripts to work correctly.
53 
54### Only Build Specific Dependencies
55 
56Only run build scripts for specific packages:
57 
58```ini
59# .npmrc
60onlyBuiltDependencies[]=esbuild
61onlyBuiltDependencies[]=sharp
62onlyBuiltDependencies[]=@swc/core
63```
64 
65Or skip builds entirely for deps that don't need them:
66 
67```json
68{
69  "pnpm": {
70    "neverBuiltDependencies": ["fsevents", "cpu-features"]
71  }
72}
73```
74 
75## Store Optimizations
76 
77### Side Effects Cache
78 
79Cache native module build results:
80 
81```ini
82# .npmrc
83side-effects-cache=true
84```
85 
86This caches the results of postinstall scripts, speeding up subsequent installs.
87 
88### Shared Store
89 
90Use a single store for all projects (default behavior):
91 
92```ini
93# .npmrc
94store-dir=~/.pnpm-store
95```
96 
97Benefits:
98- Packages downloaded once for all projects
99- Hard links save disk space
100- Faster installs from cache
101 
102### Store Maintenance
103 
104Periodically clean unused packages:
105 
106```bash
107# Remove unreferenced packages
108pnpm store prune
109 
110# Check store integrity
111pnpm store status
112```
113 
114## Workspace Optimizations
115 
116### Parallel Execution
117 
118Run workspace scripts in parallel:
119 
120```bash
121pnpm -r --parallel run build
122```
123 
124Control concurrency:
125```ini
126# .npmrc
127workspace-concurrency=8
128```
129 
130### Stream Output
131 
132See output in real-time:
133 
134```bash
135pnpm -r --stream run build
136```
137 
138### Filter to Changed Packages
139 
140Only build what changed:
141 
142```bash
143# Build packages changed since main branch
144pnpm --filter "...[origin/main]" run build
145```
146 
147### Topological Order
148 
149Build dependencies before dependents:
150 
151```bash
152pnpm -r run build
153# Automatically runs in topological order
154```
155 
156For explicit sequential builds:
157```bash
158pnpm -r --workspace-concurrency=1 run build
159```
160 
161## Network Optimizations
162 
163### Configure Registry
164 
165Use closest/fastest registry:
166 
167```ini
168# .npmrc
169registry=https://registry.npmmirror.com/
170```
171 
172### HTTP Settings
173 
174Tune network settings:
175 
176```ini
177# .npmrc
178fetch-retries=3
179fetch-retry-mintimeout=10000
180fetch-retry-maxtimeout=60000
181network-concurrency=16
182```
183 
184### Proxy Configuration
185 
186```ini
187# .npmrc
188proxy=http://proxy.company.com:8080
189https-proxy=http://proxy.company.com:8080
190```
191 
192## Lockfile Optimization
193 
194### Single Lockfile (Monorepos)
195 
196Use shared lockfile for all packages (default):
197 
198```ini
199# .npmrc
200shared-workspace-lockfile=true
201```
202 
203Benefits:
204- Single source of truth
205- Faster resolution
206- Consistent versions across workspace
207 
208### Lockfile-only Mode
209 
210Only update lockfile without installing:
211 
212```bash
213pnpm install --lockfile-only
214```
215 
216## Benchmarking
217 
218### Compare Install Times
219 
220```bash
221# Clean install
222rm -rf node_modules pnpm-lock.yaml
223time pnpm install
224 
225# Cached install (with lockfile)
226rm -rf node_modules
227time pnpm install --frozen-lockfile
228 
229# With store cache
230time pnpm install --frozen-lockfile --prefer-offline
231```
232 
233### Profile Resolution
234 
235Debug slow installs:
236 
237```bash
238# Verbose logging
239pnpm install --reporter=append-only
240 
241# Debug mode
242DEBUG=pnpm:* pnpm install
243```
244 
245## Configuration Summary
246 
247Optimized `.npmrc` for performance:
248 
249```ini
250# Install behavior
251prefer-offline=true
252auto-install-peers=true
253 
254# Build optimization  
255side-effects-cache=true
256# Only build what's necessary
257onlyBuiltDependencies[]=esbuild
258onlyBuiltDependencies[]=@swc/core
259 
260# Network
261fetch-retries=3
262network-concurrency=16
263 
264# Workspace
265workspace-concurrency=4
266```
267 
268## Quick Reference
269 
270| Scenario | Command/Setting |
271|----------|-----------------|
272| CI installs | `pnpm install --frozen-lockfile` |
273| Offline development | `--prefer-offline` |
274| Skip native builds | `neverBuiltDependencies` |
275| Parallel workspace | `pnpm -r --parallel run build` |
276| Build changed only | `pnpm --filter "...[origin/main]" build` |
277| Clean store | `pnpm store prune` |
278 
279<!-- 
280Source references:
281- https://pnpm.io/npmrc
282- https://pnpm.io/cli/install
283- https://pnpm.io/filtering
284-->
285