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 
30### Skip Optional Dependencies
31 
32If you don't need optional deps:
33 
34```bash
35pnpm install --no-optional
36```
37 
38### Skip Scripts
39 
40For CI or when scripts aren't needed:
41 
42```bash
43pnpm install --ignore-scripts
44```
45 
46**Caution:** Some packages require postinstall scripts to work correctly.
47 
48### Only Build Specific Dependencies
49 
50Build-script approval is a single `allowBuilds` map (replaces `onlyBuiltDependencies`/`neverBuiltDependencies`). Only allowed packages run install scripts:
51 
52```yaml title="pnpm-workspace.yaml"
53allowBuilds:
54  esbuild: true
55  '@swc/core': true
56  core-js: false      # explicitly skip
57```
58 
59Packages not listed are treated as unreviewed (blocked by default). See `features-supply-chain-security` for the full build-approval workflow.
60 
61## Store Optimizations
62 
63### Side Effects Cache
64 
65Cache native module build results (enabled by default):
66 
67```yaml title="pnpm-workspace.yaml"
68sideEffectsCache: true
69```
70 
71This caches the results of postinstall scripts, speeding up subsequent installs.
72 
73### Global Virtual Store
74 
75For many checkouts of the same repo (e.g. git worktrees / multiple agents), enable the global virtual store so each project's `node_modules` is just symlinks into one shared store — near-zero per-checkout cost. Auto-disabled in CI.
76 
77```yaml title="pnpm-workspace.yaml"
78enableGlobalVirtualStore: true
79```
80 
81### Shared Store
82 
83A single content-addressable store is used for all projects by default:
84 
85```yaml title="pnpm-workspace.yaml"
86storeDir: ~/.local/share/pnpm/store
87```
88 
89Benefits: packages downloaded once, hard links save disk space, faster cached installs.
90 
91### Store Maintenance
92 
93Periodically clean unused packages:
94 
95```bash
96# Remove unreferenced packages
97pnpm store prune
98 
99# Check store integrity
100pnpm store status
101```
102 
103## Workspace Optimizations
104 
105### Parallel Execution
106 
107Run workspace scripts in parallel:
108 
109```bash
110pnpm -r --parallel run build
111```
112 
113Control concurrency:
114```yaml title="pnpm-workspace.yaml"
115workspaceConcurrency: 8
116```
117 
118### Stream Output
119 
120See output in real-time:
121 
122```bash
123pnpm -r --stream run build
124```
125 
126### Filter to Changed Packages
127 
128Only build what changed:
129 
130```bash
131# Build packages changed since main branch
132pnpm --filter "...[origin/main]" run build
133```
134 
135### Topological Order
136 
137Build dependencies before dependents:
138 
139```bash
140pnpm -r run build
141# Automatically runs in topological order
142```
143 
144For explicit sequential builds:
145```bash
146pnpm -r --workspace-concurrency=1 run build
147```
148 
149## Network Optimizations
150 
151Network/registry settings are camelCase in `pnpm-workspace.yaml` (registry URLs may also go in `registries`):
152 
153```yaml title="pnpm-workspace.yaml"
154registries:
155  default: https://registry.npmmirror.com/
156fetchRetries: 3
157fetchRetryMintimeout: 10000
158fetchRetryMaxtimeout: 60000
159networkConcurrency: 16          # auto: clamp(workers x 3, 16, 64)
160httpProxy: http://proxy.company.com:8080
161httpsProxy: http://proxy.company.com:8080
162```
163 
164## Lockfile Optimization
165 
166### Single Lockfile (Monorepos)
167 
168Use shared lockfile for all packages (default):
169 
170```yaml title="pnpm-workspace.yaml"
171sharedWorkspaceLockfile: true
172```
173 
174Benefits:
175- Single source of truth
176- Faster resolution
177- Consistent versions across workspace
178 
179### Lockfile-only Mode
180 
181Only update lockfile without installing:
182 
183```bash
184pnpm install --lockfile-only
185```
186 
187## Benchmarking
188 
189### Compare Install Times
190 
191```bash
192# Clean install
193rm -rf node_modules pnpm-lock.yaml
194time pnpm install
195 
196# Cached install (with lockfile)
197rm -rf node_modules
198time pnpm install --frozen-lockfile
199 
200# With store cache
201time pnpm install --frozen-lockfile --prefer-offline
202```
203 
204### Profile Resolution
205 
206Debug slow installs:
207 
208```bash
209# Verbose logging
210pnpm install --reporter=append-only
211 
212# Debug mode
213DEBUG=pnpm:* pnpm install
214```
215 
216## Configuration Summary
217 
218Optimized `pnpm-workspace.yaml` for performance:
219 
220```yaml title="pnpm-workspace.yaml"
221# Install behavior
222autoInstallPeers: true
223sideEffectsCache: true
224optimisticRepeatInstall: true
225 
226# Build approval (only what's necessary)
227allowBuilds:
228  esbuild: true
229  '@swc/core': true
230 
231# Network
232fetchRetries: 3
233networkConcurrency: 16
234 
235# Workspace
236workspaceConcurrency: 4
237 
238# Many checkouts of the same repo
239enableGlobalVirtualStore: true
240```
241 
242## Quick Reference
243 
244| Scenario | Command/Setting |
245|----------|-----------------|
246| CI installs | `pnpm ci` / `pnpm install --frozen-lockfile` |
247| Offline development | `--prefer-offline` |
248| Control native builds | `allowBuilds` map |
249| Parallel workspace | `pnpm -r --parallel run build` |
250| Build changed only | `pnpm --filter "...[origin/main]" build` |
251| Clean store | `pnpm store prune` |
252| Many worktrees/agents | `enableGlobalVirtualStore: true` |
253 
254<!--
255Source references:
256- https://pnpm.io/settings
257- https://pnpm.io/cli/install
258- https://pnpm.io/filtering
259- https://pnpm.io/global-virtual-store
260-->
261 
262