pnpm

pnpm (Performant npm) is a package manager for Node.js that saves disk space by storing all packages in a global content-addressable store and using hard links to project node_modules. This means packages are never duplicated on disk, installs are faster, and all projects share the same cached packages.

Installation

# npm (recommended for bootstrapping)
npm install -g pnpm

# Corepack (built into Node.js 16.9+)
corepack enable
corepack prepare pnpm@latest --activate

# macOS (Homebrew)
brew install pnpm

# Windows (Scoop)
scoop install nodejs-lts
corepack enable

# Linux standalone install
curl -fsSL https://get.pnpm.io/install.sh | sh -

# Upgrade pnpm
pnpm self-update

# Check version
pnpm --version

# Set Node.js version to use (pnpm manages Node versions too)
pnpm env use --global lts
pnpm env use --global 20

Corepack Setup (Recommended)

# Enable corepack (ships with Node.js)
corepack enable pnpm

# Pin pnpm version per project in package.json
# Add to package.json:
# "packageManager": "pnpm@9.1.0"

Configuration

pnpm uses .npmrc for configuration and pnpm-workspace.yaml for monorepos:

# .npmrc
# Store location (default: ~/.pnpm-store)
store-dir=~/.pnpm-store

# Use shamefully-hoist to fix compatibility with tools that expect flat node_modules
# (only use if a package explicitly requires it)
shamefully-hoist=false

# Strict mode — fail on peer dependency issues
strict-peer-dependencies=true

# Auto-install peer dependencies
auto-install-peers=true

# Save exact versions (no ^ or ~)
save-exact=false

# Custom registry
registry=https://registry.npmjs.org/

# Scoped registry
@myorg:registry=https://npm.myorg.com/

# Link workspace packages by default
link-workspace-packages=true

# Prefer frozen lockfile in CI (set via env var instead)
# PNPM_FROZEN_LOCKFILE=true

Monorepo Workspace Config

# pnpm-workspace.yaml
packages:
  - "packages/*"
  - "apps/*"
  - "!**/__tests__/**"

package.json Overrides

{
  "pnpm": {
    "overrides": {
      "lodash": "^4.17.21",
      "minimist@<1.2.6": "^1.2.6"
    },
    "peerDependencyRules": {
      "ignoreMissing": ["react"],
      "allowAny": ["typescript"]
    },
    "packageExtensions": {
      "some-lib@*": {
        "peerDependencies": {
          "react": "*"
        }
      }
    }
  }
}

Core Commands

Command	Description
`pnpm install`	Install all dependencies
`pnpm install --frozen-lockfile`	Install without updating lockfile (CI)
`pnpm add package`	Add a dependency
`pnpm add -D package`	Add a dev dependency
`pnpm add -g package`	Install globally
`pnpm add -O package`	Add as optional dependency
`pnpm add package@2.0.0`	Add specific version
`pnpm remove package`	Remove a dependency
`pnpm update`	Update packages per semver range
`pnpm update --latest`	Update to latest versions
`pnpm update package`	Update a specific package
`pnpm outdated`	Check for outdated packages
`pnpm run script`	Run a script from package.json
`pnpm run -r script`	Run script in all workspace packages
`pnpm exec command`	Run a command from node_modules/.bin
`pnpm dlx package`	Execute package without installing (npx equivalent)
`pnpm list`	List installed packages
`pnpm list --depth 0`	List top-level packages only
`pnpm why package`	Show why a package is installed
`pnpm store status`	Check if store is up to date
`pnpm store prune`	Remove unused packages from store
`pnpm audit`	Audit packages for vulnerabilities
`pnpm patch package`	Patch a dependency
`pnpm deploy ./deploy-dir`	Create a production-ready copy
`pnpm init`	Initialize a new package.json
`pnpm publish`	Publish package to npm registry

Advanced Usage

Workspace Filtering

# Run build in a specific package
pnpm --filter my-app build

# Run tests in all packages matching pattern
pnpm --filter "*-lib" test

# Run in all packages that have changed since main
pnpm --filter "[main]" build

# Run in packages that depend on my-lib (dependents)
pnpm --filter "...my-lib" build

# Run in my-lib and all its dependencies
pnpm --filter "my-lib..." build

# Combine filters
pnpm --filter "my-app" --filter "my-lib" build

# Run in all workspace packages
pnpm -r build
pnpm -r --parallel build  # run in parallel

Dependency Patching

# Start patching a dependency
pnpm patch lodash@4.17.21

# After editing files in the temp directory printed above:
pnpm patch-commit /tmp/patch-dir

# This creates patches/lodash@4.17.21.patch and adds to package.json:
# "pnpm": { "patchedDependencies": { "lodash@4.17.21": "patches/lodash@4.17.21.patch" } }

Deploy Command (for Monorepos)

# Create a self-contained deployment directory
# Only includes the app and its workspace dependencies
pnpm --filter my-app deploy --prod ./deploy

# The deploy directory has its own node_modules with no symlinks
# Safe to copy to production server or Docker image

Catalog (pnpm 9+)

# pnpm-workspace.yaml — define shared version catalog
packages:
  - "packages/*"

catalog:
  react: "^18.3.0"
  typescript: "^5.4.0"
  vitest: "^1.6.0"

// packages/my-app/package.json
{
  "dependencies": {
    "react": "catalog:"
  },
  "devDependencies": {
    "typescript": "catalog:",
    "vitest": "catalog:"
  }
}

Content-Addressable Store

# View store location
pnpm store path

# Check store integrity
pnpm store status

# Remove unused packages (safe to run periodically)
pnpm store prune

# Add packages to store without linking (warm up cache)
pnpm fetch

Setting Up pnpm in Docker

FROM node:20-alpine

# Enable corepack and install pnpm
RUN corepack enable && corepack prepare pnpm@latest --activate

WORKDIR /app

# Copy lockfile and manifests first for layer caching
COPY pnpm-lock.yaml pnpm-workspace.yaml ./
COPY packages/my-app/package.json ./packages/my-app/
COPY packages/my-lib/package.json ./packages/my-lib/

# Install deps (uses frozen lockfile)
RUN pnpm install --frozen-lockfile

# Copy source
COPY . .
RUN pnpm --filter my-app build

Common Workflows

Setting Up a Monorepo

# Create root
mkdir my-monorepo && cd my-monorepo
pnpm init

# Create workspace config
cat > pnpm-workspace.yaml << 'EOF'
packages:
  - "packages/*"
  - "apps/*"
EOF

# Create packages
mkdir -p packages/ui apps/web
cd packages/ui && pnpm init && cd ../..
cd apps/web && pnpm init && cd ../..

# Add shared root devDependencies
pnpm add -D -w typescript vitest

# Add workspace package as dependency
pnpm --filter web add @myorg/ui --workspace

Adding Overrides to Fix Security Vulnerabilities

# Check what's vulnerable
pnpm audit

# Override the vulnerable version
# Add to package.json "pnpm.overrides":
# "vulnerable-pkg@<2.0.0": "^2.0.0"

pnpm install  # applies override
pnpm audit    # verify fix

Publishing Monorepo Packages

# Build all packages
pnpm -r build

# Publish all public packages
pnpm -r publish --access public

# Dry run to preview
pnpm -r publish --dry-run

Tips and Best Practices

Commit pnpm-lock.yaml — Always commit the lockfile. Use pnpm install --frozen-lockfile in CI to ensure deterministic installs. Set CI=true to enable this automatically.

Use pnpm dlx instead of npx — pnpm dlx is the pnpm equivalent of npx and is faster because it leverages the pnpm store for caching.

Avoid shamefully-hoist — The default strict node_modules structure catches phantom dependencies (packages you use but didn’t declare). Only enable hoisting if a specific package explicitly requires it.

Use pnpm why to audit dependencies — Before adding a package, run pnpm why package to understand if it’s already a transitive dependency you could use directly.

Prune the store periodically — Run pnpm store prune monthly to remove packages that no longer appear in any lockfile. This keeps disk usage in check.

Pin pnpm version with packageManager — Add "packageManager": "pnpm@9.x.x" to your root package.json. With corepack enabled, this ensures all contributors use the same version.

{
  "packageManager": "pnpm@9.1.0+sha256...."
}

Use the catalog for version consistency — In pnpm 9+, the workspace catalog ensures every package in a monorepo uses exactly the same version of shared tools like TypeScript, Vitest, and React — with a single place to update them.

Run scripts in parallel carefully — pnpm -r --parallel run build runs all builds simultaneously regardless of dependencies. Use --stream to see output in real time. For topology-aware ordering, use Turborepo or Nx on top of pnpm.