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<store-dir>/                # Global content-addressable store (pnpm store path)
20└── files/
21    └── <hash>/             # Files stored by content hash
22 
23project/
24└── node_modules/
25    ├── .pnpm/              # Virtual store (hard links to global store)
26    │   ├── [email protected]/
27    │   │   └── node_modules/
28    │   │       └── lodash/
29    │   └── [email protected]/
30    │       └── node_modules/
31    │           ├── express/
32    │           └── <deps>/  # Flat structure for dependencies
33    ├── lodash -> .pnpm/[email protected]/node_modules/lodash
34    └── express -> .pnpm/[email protected]/node_modules/express
35```
36 
37## Store Commands
38 
39```bash
40# Show store location
41pnpm store path
42 
43# Remove unreferenced packages
44pnpm store prune
45 
46# Check store integrity
47pnpm store status
48 
49# Add package to store without installing
50pnpm store add <pkg>
51```
52 
53## Configuration
54 
55Store/linker settings live in `pnpm-workspace.yaml` (camelCase), not `.npmrc`.
56 
57### Store Location
58 
59```yaml title="pnpm-workspace.yaml"
60storeDir: ~/.local/share/pnpm/store
61```
62 
63The default store path is OS-specific (e.g. `~/.local/share/pnpm/store` on Linux, `~/Library/pnpm/store` on macOS). Find it with `pnpm store path`.
64 
65### Virtual Store
66 
67The virtual store (`.pnpm` in `node_modules`) contains hard links to the global store:
68 
69```yaml title="pnpm-workspace.yaml"
70virtualStoreDir: node_modules/.pnpm
71virtualStoreDirMaxLength: 60   # lower this for long-path issues on Windows
72nodeLinker: hoisted            # alternative flat layout
73```
74 
75## Disk Space Benefits
76 
77pnpm saves significant disk space:
78 
79- **Deduplication**: Same package version stored once across all projects
80- **Content deduplication**: Identical files across different packages stored once
81- **Hard links**: No copying, just linking
82 
83### Check disk usage
84 
85```bash
86# Compare actual vs apparent size
87du -sh node_modules        # Apparent size
88du -sh --apparent-size node_modules  # With hard links counted
89```
90 
91## Global Virtual Store
92 
93With `enableGlobalVirtualStore: true`, projects skip the per-project `node_modules/.pnpm` directory entirely; their `node_modules` contains only symlinks into one shared virtual store at `<store-path>/links/`, keyed by dependency-graph hash. In pnpm v11 it is the default for `pnpm dlx`/`pnx` and global installs; for project installs it is still opt-in. See `features-global-virtual-store` for details and the git-worktrees multi-agent workflow.
94 
95```yaml title="pnpm-workspace.yaml"
96enableGlobalVirtualStore: true
97```
98 
99## Node Linker Modes
100 
101Configure how `node_modules` is structured (`nodeLinker` in `pnpm-workspace.yaml`):
102 
103```yaml title="pnpm-workspace.yaml"
104nodeLinker: isolated   # default: symlinked virtual store (strict, no phantom deps)
105# nodeLinker: hoisted  # flat node_modules (npm-like) for tools that dislike symlinks
106# nodeLinker: pnp      # Plug'n'Play, no node_modules (set `symlink: false` too)
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 (enabled by default):
124 
125```yaml title="pnpm-workspace.yaml"
126sideEffectsCache: true
127sideEffectsCacheReadonly: false   # only read the cache, don't create it
128```
129 
130## Read-only / Frozen Store
131 
132`frozenStore: true` (v11.7+) lets `pnpm install` run against a read-only store (Nix store, read-only bind mount, OCI layer). Pair with `--offline --frozen-lockfile`; the store must already contain everything, including approved build outputs.
133 
134```bash
135pnpm install --frozen-store --offline --frozen-lockfile
136```
137 
138## Shared Store Across Machines
139 
140For CI/CD, you can share the store:
141 
142```yaml
143# GitHub Actions example
144- uses: pnpm/action-setup@v4
145  with:
146    run_install: false
147 
148- name: Get pnpm store directory
149  shell: bash
150  run: echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
151 
152- uses: actions/cache@v4
153  with:
154    path: ${{ env.STORE_PATH }}
155    key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
156```
157 
158## Troubleshooting
159 
160### Store corruption
161```bash
162# Verify and fix store
163pnpm store status
164pnpm store prune
165```
166 
167### Hard link issues (network drives, Docker)
168```yaml title="pnpm-workspace.yaml"
169# auto (default) tries clone -> hardlink -> copy
170packageImportMethod: copy
171```
172 
173### Permission issues
174```bash
175# Fix store permissions (find the path with `pnpm store path`)
176chmod -R u+w "$(pnpm store path)"
177```
178 
179<!--
180Source references:
181- https://pnpm.io/symlinked-node-modules-structure
182- https://pnpm.io/cli/store
183- https://pnpm.io/settings#storedir
184- https://pnpm.io/global-virtual-store
185-->
186