0
# Store Management
1

2
Manage the global package store, inspect cached packages, and optimize disk usage with pnpm's content-addressable storage operations.
3

4
## Capabilities
5

6
### Store Operations
7

8
Manage the global pnpm store where all packages are cached using content-addressable storage.
9

10
```bash { .api }
11
/**
12
 * Manage the global package store
13
 * Controls content-addressable storage for all packages
14
 */
15
pnpm store <command> [options]
16
```
17

18
**Available Commands:**
19
- `status` - Show store status and statistics
20
- `path` - Show store directory path
21
- `prune` - Remove unreferenced packages from store
22
- `add` - Add packages to store without installing
23

24
**Usage Examples:**
25

26
```bash
27
# Show store status
28
pnpm store status
29

30
# Show store path
31
pnpm store path
32

33
# Clean up unused packages
34
pnpm store prune
35

36
# Add package to store
37
pnpm store add react@18.2.0
38
```
39

40
### Store Status
41

42
Get detailed information about store usage, size, and package counts.
43

44
```bash { .api }
45
/**
46
 * Show store status and statistics
47
 * Displays store size, package count, and cleanup recommendations
48
 */
49
pnpm store status [options]
50
```
51

52
**Usage Examples:**
53

54
```bash
55
# Show basic store status
56
pnpm store status
57

58
# Show detailed store information
59
pnpm store status --verbose
60
```
61

62
### Store Path
63

64
Display the location of the global package store directory.
65

66
```bash { .api }
67
/**
68
 * Show store directory path
69
 * Returns absolute path to content-addressable store
70
 */
71
pnpm store path [options]
72
```
73

74
**Usage Examples:**
75

76
```bash
77
# Show store path
78
pnpm store path
79

80
# Use store path in scripts
81
STORE_PATH=$(pnpm store path)
82
```
83

84
### Store Pruning
85

86
Remove unreferenced packages from the store to reclaim disk space.
87

88
```bash { .api }
89
/**
90
 * Remove unreferenced packages from store
91
 * Cleans up packages not used by any project
92
 */
93
pnpm store prune [options]
94
```
95

96
**Options:**
97
- `--force` - Force removal without confirmation
98
- `--dry-run` - Show what would be removed without doing it
99

100
**Usage Examples:**
101

102
```bash
103
# Prune unused packages (with confirmation)
104
pnpm store prune
105

106
# Force prune without confirmation
107
pnpm store prune --force
108

109
# Show what would be pruned
110
pnpm store prune --dry-run
111
```
112

113
### Store Add
114

115
Add packages to the store without installing them to any project.
116

117
```bash { .api }
118
/**
119
 * Add packages to store without installing
120
 * Pre-populates store for faster subsequent installs
121
 */
122
pnpm store add <pkg>[@version] [options]
123
```
124

125
**Usage Examples:**
126

127
```bash
128
# Add package to store
129
pnpm store add react
130

131
# Add specific version
132
pnpm store add react@18.2.0
133

134
# Add multiple packages
135
pnpm store add react vue angular
136
```
137

138
## Store Inspection
139

140
### Inspect Files by Hash
141

142
View the contents of files in the store using their content hash.
143

144
```bash { .api }
145
/**
146
 * Show file contents from store by hash
147
 * Displays content of files using content-addressable hash
148
 */
149
pnpm cat-file <hash> [options]
150
```
151

152
**Usage Examples:**
153

154
```bash
155
# Show file contents by hash
156
pnpm cat-file 1a2b3c4d5e6f7890abcdef1234567890abcdef12
157

158
# Show file with specific encoding
159
pnpm cat-file --encoding=utf8 1a2b3c4d5e6f
160
```
161

162
### Inspect Package Index
163

164
View the package index from the store showing package metadata and file structure.
165

166
```bash { .api }
167
/**
168
 * Show package index from store
169
 * Displays package metadata and file structure
170
 */
171
pnpm cat-index [options]
172
```
173

174
**Options:**
175
- `--package <name>` - Show index for specific package
176
- `--registry <url>` - Use specific registry
177

178
**Usage Examples:**
179

180
```bash
181
# Show package index
182
pnpm cat-index
183

184
# Show index for specific package
185
pnpm cat-index --package react
186

187
# Show index from specific registry
188
pnpm cat-index --registry https://registry.npmjs.org
189
```
190

191
### Find Packages by Hash
192

193
Find packages in the store that contain a specific hash.
194

195
```bash { .api }
196
/**
197
 * Find packages containing specific hash
198
 * Searches store for packages with matching content hash
199
 */
200
pnpm find-hash <hash> [options]
201
```
202

203
**Usage Examples:**
204

205
```bash
206
# Find packages with hash
207
pnpm find-hash 1a2b3c4d5e6f7890
208

209
# Find with partial hash
210
pnpm find-hash 1a2b3c
211
```
212

213
## Cache Management
214

215
### Cache Operations
216

217
Manage package cache for improved performance and storage optimization.
218

219
```bash { .api }
220
/**
221
 * Manage package cache operations
222
 * Controls caching behavior for faster installs
223
 */
224
pnpm cache <command> [options]
225
```
226

227
**Available Commands:**
228
- `verify` - Verify cache integrity
229
- `clean` - Clean cache data
230

231
**Usage Examples:**
232

233
```bash
234
# Verify cache integrity
235
pnpm cache verify
236

237
# Clean cache
238
pnpm cache clean
239
```
240

241
### Cache Verification
242

243
Verify the integrity of cached packages and metadata.
244

245
```bash { .api }
246
/**
247
 * Verify cache integrity
248
 * Checks cached packages for corruption or inconsistencies
249
 */
250
pnpm cache verify [options]
251
```
252

253
**Usage Examples:**
254

255
```bash
256
# Verify all cached data
257
pnpm cache verify
258

259
# Verify with detailed output
260
pnpm cache verify --verbose
261
```
262

263
### Cache Cleaning
264

265
Clean cached data to free up disk space and resolve cache issues.
266

267
```bash { .api }
268
/**
269
 * Clean cache data
270
 * Removes cached metadata and temporary files
271
 */
272
pnpm cache clean [options]
273
```
274

275
**Options:**
276
- `--force` - Force cleaning without confirmation
277

278
**Usage Examples:**
279

280
```bash
281
# Clean cache (with confirmation)
282
pnpm cache clean
283

284
# Force clean without confirmation
285
pnpm cache clean --force
286
```
287

288
## Store Configuration
289

290
### Store Location
291

292
Configure the location of the global package store.
293

294
```bash { .api }
295
# Set store directory via config
296
pnpm config set store-dir /path/to/store
297

298
# Set via environment variable
299
export PNPM_STORE_PATH=/path/to/store
300

301
# Set via .pnpmrc file
302
store-dir=/path/to/store
303
```
304

305
### Store Settings
306

307
Configure store behavior and optimization settings.
308

309
```bash { .api }
310
# Store configuration options
311
store-dir                    # Store directory path
312
verify-store-integrity      # Verify packages when adding to store
313
package-import-method       # How to import packages (hardlink, copy, clone)
314
```
315

316
**Configuration Examples:**
317

318
```bash
319
# Set store directory
320
pnpm config set store-dir ~/.pnpm-store
321

322
# Enable store verification
323
pnpm config set verify-store-integrity true
324

325
# Set package import method
326
pnpm config set package-import-method hardlink
327
```
328

329
## Store Architecture
330

331
### Content-Addressable Storage
332

333
Understanding pnpm's content-addressable storage system:
334

335
```bash { .api }
336
# Store structure
337
<store>/
338
├── v3/                    # Store format version
339
│   ├── files/            # Content-addressable files
340
│   │   ├── 00/           # Hash-based directory structure
341
│   │   │   └── 1a2b3c... # File content by hash
342
│   └── metadata/         # Package metadata
343
└── tmp/                  # Temporary files
344
```
345

346
### Hard Links and Symlinks
347

348
pnpm uses hard links and symlinks to share packages efficiently:
349

350
```bash { .api }
351
# Installation structure
352
node_modules/
353
├── .pnpm/                    # Virtual store
354
│   ├── package@1.0.0/       # Actual package files (hard links to store)
355
│   └── node_modules/         # Dependency structure
356
└── package/                  # Symlink to .pnpm/package@1.0.0
357
```
358

359
### Store Benefits
360

361
Key advantages of pnpm's store architecture:
362

363
```bash { .api }
364
# Performance benefits
365
- Faster installs (packages cached globally)
366
- Reduced disk usage (shared packages via hard links)
367
- Atomic installs (packages linked, not copied)
368
- Offline installs (cached packages available)
369

370
# Security benefits  
371
- Dependency isolation (hoisting limitations)
372
- Integrity verification (content-addressable hashing)
373
- Reproducible installs (deterministic linking)
374
```
375

376
## Troubleshooting Store Issues
377

378
### Store Corruption
379

380
Resolve store corruption issues:
381

382
```bash { .api }
383
# Verify store integrity
384
pnpm store status
385

386
# Prune corrupted packages
387
pnpm store prune --force
388

389
# Clear cache if needed
390
pnpm cache clean --force
391

392
# Reinstall if corruption persists
393
rm -rf node_modules pnpm-lock.yaml
394
pnpm install
395
```
396

397
### Disk Space Issues
398

399
Manage disk space usage:
400

401
```bash { .api }
402
# Check store size
403
pnpm store status
404

405
# Remove unused packages
406
pnpm store prune
407

408
# Clean cache data
409
pnpm cache clean
410

411
# Move store to different location
412
pnpm config set store-dir /path/to/new/store
413
```
414

415
### Permission Issues
416

417
Resolve store permission problems:
418

419
```bash { .api }
420
# Fix store permissions
421
chmod -R 755 $(pnpm store path)
422

423
# Use different store location
424
pnpm config set store-dir ~/.local/share/pnpm/store
425

426
# Run with specific user permissions
427
sudo -u $USER pnpm install
428
```
429

430
## Store Server Operations
431

432
### Store Server Management
433

434
Start and manage the pnpm store server for improved performance in development environments.
435

436
```bash { .api }
437
/**
438
 * Manage pnpm store server
439
 * Starts/stops background server for faster package operations
440
 */
441
pnpm server <command> [options]
442
```
443

444
**Commands:**
445
- `start` - Start the store server
446
- `stop` - Stop the store server  
447
- `status` - Check server status
448

449
**Usage Examples:**
450

451
```bash
452
# Start store server
453
pnpm server start
454

455
# Check server status
456
pnpm server status
457

458
# Stop store server
459
pnpm server stop
460
```
461

462
The store server provides:
463
- Faster package resolution through background caching
464
- Reduced startup time for repeated operations
465
- Improved performance for workspace operations
466
- Background dependency pre-fetching