pnmp Installation Guide

1️⃣ Prerequisites

Item	Minimum	Recommended	Why it matters
Operating System	Linux/macOS/Windows 10 + (WSL 2 on Windows)	Any modern OS	The installer scripts rely on native shells.
Node.js	v18.12.0 or newer (>=18.0)	v20+	pnpm is built in pure JavaScript, but newer Node releases bring performance and bug fixes.
npm (for the official install script)	v6.14.0 or newer	v8+	Required only if you use npm i -g pnpm or the npx shortcut.
Git (optional but handy)	Latest stable	Latest stable	Useful for cloning the repo or for debugging.
C++ Build Tools (Windows)	MSVC 14.29+ (Visual Studio 2019 +), or Build Tools for Visual Studio 2022	Same	Needed for native add-ons that pnpm might install.
Python 2.7 / 3.8+ (Windows)	3.8+	3.10+	Required by some Node‑Python bindings.

Tip: Most users can skip installing build tools if they’re not planning to compile native add‑ons. pnpm will fall back to pre‑built binaries when available.

---

2️⃣ Installation Methods

Below are the most common ways to install pnpm. Pick the one that best fits your workflow.

2.1. From npm (classic)

# Global install
npm install -g pnpm

Pros: Straightforward, works on all npm‑enabled environments.
Cons: Requires npm and may pull an older version if your npm cache is stale.

2.2. Using the official install script

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

Pros: Installs the latest pnpm version, bypasses npm.
Cons: Requires curl and sh; on Windows you’ll need WSL or Git‑Bash.

On Windows use PowerShell:

iwr https://get.pnpm.io/install.ps1 -useb | iex

2.3. via npx

npx pnpm add -g <package>

Pros: No global install; runs the latest version each time.
Cons: Slightly slower startup; needs network each run.

2.4. Homebrew (macOS / Linux)

brew install pnpm

Pros: Managed by Homebrew, updates via brew upgrade.
Cons: Only for macOS/Linux; not a cross‑platform solution.

2.5. Windows Chocolatey

choco install pnpm

2.6. Docker

If you want to use pnpm in a containerised environment:

FROM node:20-alpine
RUN npm install -g pnpm
WORKDIR /app

2.7. Binary ZIP / TGZ (Manual)

Download the latest release from the GitHub releases page and extract. Add the extracted pnpm binary to your $PATH.

---

3️⃣ Configuration

pnpm can be configured in three main ways:

1. CLI flags – temporary for a single command.
2. Environment variables – persistent per shell session.
3. .npmrc/pnpmfile.js – project‑ or user‑wide config.

3.1. Common CLI Flags

Flag	Description
--save / -S	Adds package to dependencies.
--save-dev / -D	Adds to devDependencies.
--save-optional	Adds to optionalDependencies.
--prod	Installs only dependencies.
--no-optional	Skips optional deps.
--frozen-lockfile	Fails if lockfile is out of sync.
--prefer-offline	Uses local cache before network.
--strict-peer-dependencies	Enforces peer dependency satisfaction.

3.2. Environment Variables

Variable	Default	Effect
PNPM_HOME	None	Custom install dir for global packages.
PNPM_HOME_NODE	Auto‑detected	Path to Node binary.
PNPM_CACHE	~/.pnpm-store	Cache location.
PNPM_WORKSPACE_ROOT	Auto	Root of a pnpm workspace.
PNPM_REGISTRY	https://registry.npmjs.org/	Custom registry URL.
PNPM_LOGLEVEL	notice	Verbosity of logs.
PNPM_PRODUCTION	false	Whether to skip dev deps.

Example: Force offline mode for the next install:

export PNPM_PREFETCH=1
pnpm install --prefer-offline

3.3. .npmrc (or .pnpmrc)

Add configuration per project or globally. Global config lives in ~/.npmrc. Example:

# .npmrc
save-exact=true
registry=https://registry.yarnpkg.com
prefer-offline=true
frozen-lockfile=true

You can also create a pnpmfile.js for advanced overrides, like patching a dependency before install.

module.exports = {
  hooks: {
    readPackage(pkg) {
      if (pkg.name === 'foo') {
        pkg.dependencies.bar = '1.2.3';
      }
      return pkg;
    }
  }
};

3.4. Workspaces

pnpm shines in monorepos. Create a pnpm-workspace.yaml:

packages:
  - "packages/*"
  - "apps/*"

Then run pnpm install from the root, and pnpm will hoist shared dependencies to the workspace root, saving space and speeding up installs.

---

4️⃣ Troubleshooting

Symptom	Likely Cause	Fix / Work‑around
pnpm: command not found	PATH not updated	Re‑source shell profile (source ~/.bashrc) or restart terminal.
Cannot find module ... after pnpm install	Broken lockfile or corrupted node_modules	Run pnpm store prune && pnpm install or delete node_modules & pnpm-lock.yaml.
EPERM or EACCES during global install	Permission denied on /usr/local or Windows global dir	Use sudo on Linux/macOS, or install with --prefix ~/.local. On Windows run PowerShell as Administrator.
UNSUPPORTED error for binary add-ons	Missing build tools	Install build‑tools for your platform (MSVC, gcc, Python).
Network timeouts	Corporate proxy / firewall	Set pnpm config set proxy http://proxy:port and pnpm config set https-proxy http://proxy:port.
Version mismatch (ERR_PNPM_NOT_IN_LOCKFILE)	Manual edits to package.json	Run pnpm install again to regenerate lockfile.
ERR_PNPM_EARLY (duplicate peer deps)	Peer dependency conflicts	Add --strict-peer-dependencies=false or resolve the conflict in your package.json.
pnpm refuses to install due to lockfile differences	frozen-lockfile set but lockfile outdated	Remove the flag or run pnpm install --frozen-lockfile to verify.

Tip: Running pnpm doctor (introduced in v8) prints a diagnostic report that can catch many misconfigurations automatically.

---

5️⃣ Resources

Resource	What it Offers	URL
Official documentation	Guides, API, CLI reference	https://pnpm.io
GitHub repository	Source code, issue tracker	https://github.com/pnpm/pnpm
pnpm Discord	Community chat, quick help	https://discord.com/invite/pnpm
npm Registry	Package source	https://www.npmjs.com
Yarn Registry	Alternative registry	https://registry.yarnpkg.com
Tutorials	“From zero to monorepo” videos	https://www.youtube.com/results?search_query=pnpm+tutorial
Community blog posts	Best practices	https://medium.com/tag/pnpm
GitHub Actions	CI examples with pnpm	https://github.com/pnpm/action

---

Quick Reference Cheat‑Sheet

Command	What it does
pnpm add <pkg>	Add to dependencies.
pnpm add -D <pkg>	Add to devDependencies.
pnpm install	Install all deps from lockfile.
pnpm install --frozen-lockfile	Fail if lockfile out of sync.
pnpm update <pkg>	Update a specific dependency.
pnpm recursive install	Install across all workspaces.
pnpm cache clean	Clear local cache.
pnpm doctor	Run diagnostics.