1---
2name: pnpm-store
3description: Content-addressable storage system that makes pnpm fast and disk-efficient
4---
5 
6# pnpm Store
7 
8pnpm uses a content-addressable store to save disk space and speed up installations. All packages are stored once globally and hard-linked to project `node_modules`.
9 
10## How It Works
11 
121. **Global Store**: Packages are downloaded once to a central store
132. **Hard Links**: Projects link to store instead of copying files
143. **Content-Addressable**: Files are stored by content hash, deduplicating identical files
15 
16### Storage Layout
17 
18```
19~/.pnpm-store/              # Global store (default location)
20└── v3/
21    └── files/
22        └── <hash>/         # Files stored by content hash
23 
24project/
25└── node_modules/
26    ├── .pnpm/              # Virtual store (hard links to global store)
27    │   ├── [email protected]/
28    │   │   └── node_modules/
29    │   │       └── lodash/
30    │   └── [email protected]/
31    │       └── node_modules/
32    │           ├── express/
33    │           └── <deps>/  # Flat structure for dependencies
34    ├── lodash -> .pnpm/[email protected]/node_modules/lodash
35    └── express -> .pnpm/[email protected]/node_modules/express
36```
37 
38## Store Commands
39 
40```bash
41# Show store location
42pnpm store path
43 
44# Remove unreferenced packages
45pnpm store prune
46 
47# Check store integrity
48pnpm store status
49 
50# Add package to store without installing
51pnpm store add <pkg>
52```
53 
54## Configuration
55 
56### Store Location
57 
58```ini
59# .npmrc
60store-dir=~/.pnpm-store
61 
62# Or use environment variable
63PNPM_HOME=~/.local/share/pnpm
64```
65 
66### Virtual Store
67 
68The virtual store (`.pnpm` in `node_modules`) contains symlinks to the global store:
69 
70```ini
71# Customize virtual store location
72virtual-store-dir=node_modules/.pnpm
73 
74# Alternative flat layout
75node-linker=hoisted
76```
77 
78## Disk Space Benefits
79 
80pnpm saves significant disk space:
81 
82- **Deduplication**: Same package version stored once across all projects
83- **Content deduplication**: Identical files across different packages stored once
84- **Hard links**: No copying, just linking
85 
86### Check disk usage
87 
88```bash
89# Compare actual vs apparent size
90du -sh node_modules        # Apparent size
91du -sh --apparent-size node_modules  # With hard links counted
92```
93 
94## Node Linker Modes
95 
96Configure how `node_modules` is structured:
97 
98```ini
99# Default: Symlinked structure (recommended)
100node-linker=isolated
101 
102# Flat node_modules (npm-like, for compatibility)
103node-linker=hoisted
104 
105# PnP mode (experimental, like Yarn PnP)
106node-linker=pnp
107```
108 
109### Isolated Mode (Default)
110 
111- Strict dependency resolution
112- No phantom dependencies
113- Packages can only access declared dependencies
114 
115### Hoisted Mode
116 
117- Flat `node_modules` like npm
118- For compatibility with tools that don't support symlinks
119- Loses strictness benefits
120 
121## Side Effects Cache
122 
123Cache build outputs for native modules:
124 
125```ini
126# Enable side effects caching
127side-effects-cache=true
128 
129# Store side effects in project (instead of global store)
130side-effects-cache-readonly=true
131```
132 
133## Shared Store Across Machines
134 
135For CI/CD, you can share the store:
136 
137```yaml
138# GitHub Actions example
139- uses: pnpm/action-setup@v4
140  with:
141    run_install: false
142 
143- name: Get pnpm store directory
144  shell: bash
145  run: echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
146 
147- uses: actions/cache@v4
148  with:
149    path: ${{ env.STORE_PATH }}
150    key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
151```
152 
153## Troubleshooting
154 
155### Store corruption
156```bash
157# Verify and fix store
158pnpm store status
159pnpm store prune
160```
161 
162### Hard link issues (network drives, Docker)
163```ini
164# Use copying instead of hard links
165package-import-method=copy
166```
167 
168### Permission issues
169```bash
170# Fix store permissions
171chmod -R u+w ~/.pnpm-store
172```
173 
174<!-- 
175Source references:
176- https://pnpm.io/symlinked-node-modules-structure
177- https://pnpm.io/cli/store
178- https://pnpm.io/npmrc#store-dir
179-->
180