Pnpm

name: pnpm-performance-optimization description: Tips and tricks for faster installs and better performance

pnpm Performance Optimization

pnpm is fast by default, but these optimizations can make it even faster.

Install Optimizations

Use Frozen Lockfile

Skip resolution when lockfile exists:

pnpm install --frozen-lockfile

This is faster because pnpm skips the resolution phase entirely.

Prefer Offline Mode

Use cached packages when available:

pnpm install --prefer-offline

Skip Optional Dependencies

If you don't need optional deps:

pnpm install --no-optional   # or `optional: false` in pnpm-workspace.yaml

On pnpm 12, --force still skips optional deps built for other platforms unless forceIgnoresPlatform: true; prefer supportedArchitectures to install other platforms on purpose.

Skip Scripts

For CI or when scripts aren't needed:

pnpm install --ignore-scripts

Caution: Some packages require postinstall scripts to work correctly.

Only Build Specific Dependencies

Build-script approval is a single allowBuilds map (replaces onlyBuiltDependencies/neverBuiltDependencies). Only allowed packages run install scripts:

allowBuilds:
  esbuild: true
  '@swc/core': true
  core-js: false      # explicitly skip

Packages not listed are treated as unreviewed (blocked by default). See features-supply-chain-security for the full build-approval workflow.

Store Optimizations

Side Effects Cache

Cache native module build results (enabled by default):

sideEffectsCache: true

This caches the results of postinstall scripts, speeding up subsequent installs. Object form: read, write, remote, and exclude (v12.14.0) for packages whose build depends on things pnpm cannot key on, such as system libraries:

sideEffectsCache:
  exclude: ['[email protected] || 2.0.0', '@native/*']   # always built locally, never cached

Builds can also be shared across machines with sideEffectsCache.remote and the remoteCache setting (v12.12.0; a pnpr server or a Turborepo Remote Cache API server such as Vercel). Publishing and signing keys may only be set in global config or env.

Global Virtual Store

For many checkouts of the same repo (e.g. git worktrees / multiple agents), enable the global virtual store so each project's node_modules is just symlinks into one shared store — near-zero per-checkout cost. Auto-disabled in CI. Only applies with nodeLinker: isolated; pnpm dlx/pnx do not use it.

virtualStoreType: global

Shared Store

A single content-addressable store is used for all projects by default:

storeDir: ~/.local/share/pnpm/store

Benefits: packages downloaded once, hard links save disk space, faster cached installs.

Store Maintenance

Periodically clean unused packages:

# Remove unreferenced packages
pnpm store prune

# Check store integrity
pnpm store status

Workspace Optimizations

Parallel Execution

Run workspace scripts in parallel:

pnpm -r --parallel run build

Control concurrency:

workspaceConcurrency: 8

Stream Output

See output in real-time:

pnpm -r --stream run build

Filter to Changed Packages

Only build what changed:

# Build packages changed since main branch
pnpm --filter "...[origin/main]" run build

Topological Order

Build dependencies before dependents:

pnpm -r run build
# Automatically runs in topological order

For explicit sequential builds:

pnpm -r --workspace-concurrency=1 run build

Network Optimizations

Network/registry settings are camelCase in pnpm-workspace.yaml (registry URLs may also go in registries):

registries:
  default: https://registry.npmmirror.com/
fetchRetries: 3
fetchRetryMintimeout: 10000
fetchRetryMaxtimeout: 60000
networkConcurrency: 64          # auto: clamp(workers x 3, 64, 96)
httpProxy: http://proxy.company.com:8080
httpsProxy: http://proxy.company.com:8080

Lockfile Optimization

Single Lockfile (Monorepos)

Use shared lockfile for all packages (default):

sharedWorkspaceLockfile: true

Benefits:

• Single source of truth

• Faster resolution

• Consistent versions across workspace

Lockfile-only Mode

Only update lockfile without installing:

pnpm install --lockfile-only

Benchmarking

Compare Install Times

# Clean install
rm -rf node_modules pnpm-lock.yaml
time pnpm install

# Cached install (with lockfile)
rm -rf node_modules
time pnpm install --frozen-lockfile

# With store cache
time pnpm install --frozen-lockfile --prefer-offline

Profile Resolution

Debug slow installs:

# Verbose logging
pnpm install --reporter=append-only

# Debug mode
DEBUG=pnpm:* pnpm install

Configuration Summary

Optimized pnpm-workspace.yaml for performance:

# Install behavior
autoInstallPeers: true
sideEffectsCache: true
optimisticRepeatInstall: true

# Build approval (only what's necessary)
allowBuilds:
  esbuild: true
  '@swc/core': true

# Network
fetchRetries: 3
networkConcurrency: 64

# Workspace
workspaceConcurrency: 4

# Many checkouts of the same repo
virtualStoreType: global

Quick Reference

<!-- Source references: - https://pnpm.io/settings - https://pnpm.io/cli/install - https://pnpm.io/filtering - https://pnpm.io/global-virtual-store -->