0
# pnpm
1

2
pnpm is a fast, disk space efficient package manager for Node.js that uses hard links and symlinks to share dependencies across projects. It offers up to 2x faster performance than alternatives, strict dependency isolation ensuring packages can only access dependencies explicitly declared in their package.json, deterministic installations with pnpm-lock.yaml lockfiles, and excellent monorepo support with workspace features.
3

4
## Package Information
5

6
- **Package Name**: pnpm
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install -g pnpm` or `curl -fsSL https://get.pnpm.io/install.sh | sh -`
10

11
## Core Usage
12

13
### Binary Executables
14

15
```bash { .api }
16
# Main pnpm executable
17
pnpm [command] [options]
18

19
# Package runner (equivalent to npx)
20
pnpx [package] [args]
21
```
22

23
### Basic Package Management
24

25
```bash
26
# Install all dependencies
27
pnpm install
28

29
# Add new packages
30
pnpm add lodash
31
pnpm add -D typescript  # dev dependency
32
pnpm add -g pm2         # global package
33

34
# Remove packages
35
pnpm remove lodash
36

37
# Update packages
38
pnpm update lodash
39
```
40

41
### Script Running
42

43
```bash
44
# Run package scripts
45
pnpm run dev
46
pnpm start
47

48
# Execute packages without installing
49
pnpm dlx create-react-app my-app
50

51
# Execute in package context
52
pnpm exec tsc --version
53
```
54

55
## Architecture
56

57
pnpm is built around several key architectural components:
58

59
- **Content-Addressable Store**: Single global store for all packages using hard links and symlinks
60
- **Plugin Architecture**: Modular command system with plugins for different functionality areas
61
- **Workspace Support**: First-class monorepo support with workspace filtering and dependency management  
62
- **Lockfile System**: Deterministic pnpm-lock.yaml format ensuring reproducible installations
63
- **Node.js Version Management**: Integrated support for switching Node.js versions per project
64
- **CLI Framework**: Extensible command-line interface with auto-completion and help system
65

66
## Capabilities
67

68
### Package Management
69

70
Core package management operations including installation, adding/removing dependencies, and updating packages. Provides faster installs through hard linking and strict dependency isolation.
71

72
```bash { .api }
73
# Install dependencies
74
pnpm install [options]
75
pnpm i [options]
76

77
# Add packages
78
pnpm add <pkg>[@version] [options]
79

80
# Remove packages  
81
pnpm remove <pkg> [options]
82
pnpm rm <pkg> [options]
83
pnpm uninstall <pkg> [options]
84

85
# Update packages
86
pnpm update [pkg] [options]
87
pnpm up [pkg] [options]
88

89
# Pack and publish packages
90
pnpm pack [options]
91
pnpm publish [tarball|folder] [options]
92
```
93

94
[Package Management](./package-management.md)
95

96
### Script Running and Execution
97

98
Execute package scripts, run packages without installing, and manage development workflows with comprehensive script running capabilities.
99

100
```bash { .api }
101
# Run package scripts
102
pnpm run <script> [options]
103
pnpm run-script <script> [options]
104

105
# Execute packages without installing (like npx)
106
pnpm dlx <pkg> [args]
107

108
# Execute commands in package context
109
pnpm exec <command> [options]
110

111
# Create projects from templates
112
pnpm create <template> [options]
113
```
114

115
[Script Running](./script-running.md)
116

117
### Workspace Management
118

119
Monorepo and workspace operations with filtering, recursive commands, and cross-package dependency management for complex multi-package projects.
120

121
```bash { .api }
122
# Recursive commands across workspace
123
pnpm -r <command> [options]
124
pnpm --recursive <command> [options]
125

126
# Filter workspace packages
127
pnpm --filter <pattern> <command>
128
pnpm -F <pattern> <command>
129

130
# Deploy workspace packages
131
pnpm deploy [options]
132
```
133

134
[Workspace Management](./workspace-management.md)
135

136
### Store and Cache Management
137

138
Manage the global package store, inspect cached packages, and optimize disk usage with content-addressable storage operations.
139

140
```bash { .api }
141
# Store operations
142
pnpm store <command> [options]
143

144
# Cache operations  
145
pnpm cache <command> [options]
146

147
# Store inspection
148
pnpm cat-file <hash> [options]
149
pnpm cat-index [options]
150
pnpm find-hash <hash> [options]
151

152
# Store server operations
153
pnpm server <command> [options]
154
```
155

156
[Store Management](./store-management.md)
157

158
### Configuration and Environment
159

160
Configure pnpm settings, manage Node.js environments, and set up shell integrations for optimal development workflows.
161

162
```bash { .api }
163
# Configuration management
164
pnpm config <command> [options]
165
pnpm get <key> [options]
166
pnpm set <key> <value> [options]
167

168
# Environment management
169
pnpm env <command> [options]
170
pnpm setup [options]
171

172
# System information
173
pnpm bin [options]
174
pnpm root [options]
175

176
# Project and system management
177
pnpm init [options]
178
pnpm doctor [options]
179
```
180

181
[Configuration](./configuration.md)
182

183
### Package Inspection and Analysis
184

185
Inspect installed packages, check for outdated dependencies, audit security vulnerabilities, and analyze package relationships.
186

187
```bash { .api }
188
# List packages
189
pnpm list [pkg] [options]
190
pnpm ls [pkg] [options]
191
pnpm ll [options]
192

193
# Check package relationships
194
pnpm why <pkg> [options]
195

196
# Check for updates
197
pnpm outdated [pkg] [options]
198

199
# Security audit
200
pnpm audit [options]
201
```
202

203
[Package Inspection](./package-inspection.md)
204

205
## Global Options
206

207
Options available for all pnpm commands:
208

209
```bash { .api }
210
--color <always|auto|never>     # Control colored output
211
--dir <path>                    # Change working directory  
212
--filter <pattern>              # Filter workspace packages
213
--filter-prod <pattern>         # Filter production dependencies
214
--loglevel <level>              # Set logging level (silent, error, warn, info, verbose, silly)
215
--parseable                     # Machine-readable output
216
--reporter <type>               # Set reporter type (default, silent, append-only)
217
--recursive                     # Run recursively in workspace
218
--workspace-root               # Include workspace root
219
--help                         # Show help information
220
--version                      # Show version information
221
```
222

223
## Universal Shorthands
224

225
Common shorthand options:
226

227
```bash { .api }
228
# Single-letter shorthands
229
-r          # --recursive
230
-s          # --reporter=silent  
231
-d          # --loglevel=info
232
-dd         # --loglevel=verbose
233
-ddd        # --loglevel=silly
234
-q          # --loglevel=warn
235
-h          # --help
236
-H          # --help (alternative)
237
-?          # --help (alternative)
238
-v          # --version
239
-f          # --force
240
-g          # --global
241
-l          # --long
242
-p          # --parseable
243
-i          # --interactive
244
-L          # --latest
245
-S          # --save
246
-D          # --save-dev
247
-P          # --save-prod
248
-E          # --save-exact
249
-O          # --save-optional
250
-C          # --dir
251
-F          # --filter
252
-w          # --workspace-root
253

254
# Word-form shorthands
255
silent      # --reporter=silent
256
verbose     # --loglevel=verbose
257
quiet       # --loglevel=warn
258
usage       # --help
259
local       # --no-global
260
porcelain   # --parseable
261
prod        # --production
262
development # --dev
263
```
264

265
## NPM Compatibility
266

267
pnpm automatically passes through certain commands to npm for full compatibility:
268

269
```bash { .api }
270
# These commands are forwarded to npm
271
pnpm access
272
pnpm adduser  
273
pnpm bugs
274
pnpm deprecate
275
pnpm dist-tag
276
pnpm docs
277
pnpm edit
278
pnpm find
279
pnpm home
280
pnpm info
281
pnpm issues
282
pnpm login
283
pnpm logout
284
pnpm owner
285
pnpm ping
286
pnpm prefix
287
pnpm profile
288
pnpm pkg
289
pnpm repo
290
pnpm s           # search alias
291
pnpm se          # search alias
292
pnpm search
293
pnpm set-script  
294
pnpm show
295
pnpm star
296
pnpm stars
297
pnpm team
298
pnpm token
299
pnpm unpublish
300
pnpm unstar
301
pnpm v           # version alias
302
pnpm version
303
pnpm view
304
pnpm whoami
305
pnpm xmas        # Easter egg command
306
```