Victor's room

Overview & Root Cause Summary: The error bash: pnpm: command not found (or zsh: command not found: pnpm) occurs when the shell cannot resolve the pnpm binary in the active PATH environment variable. Unlike npm, pnpm is not pre-bundled into standalone Node.js runtime packages. This error typically happens when Corepack is unactivated, when the official standalone shell installer’s PNPM_HOME directory was not sourced into the current shell session, or when global npm bin directories are excluded from PATH.

Understanding the Root Causes

• Unbundled Package Manager: Node.js official installers distribute npm by default, but exclude alternative package managers like pnpm and Yarn from default binaries.
• Corepack Shims Unactivated: Node.js includes Corepack to manage pnpm versions, but its global executable shims remain disabled until corepack enable is explicitly executed.
• Missing PNPM_HOME Environment Variable: The official curl/powershell standalone installation script configures paths in ~/.bashrc or ~/.zshrc, but existing terminal tabs or subshells have not reloaded the profile.
• CI/CD Runner and Subshell Path Gaps: Non-interactive automated CI/CD runners or cron jobs executing without user profile dotfiles loaded.

Step 1: Quick Fix (Enable Built-in Corepack Shims)

If you have modern Node.js installed, activate pnpm immediately using Node’s built-in Corepack tool without downloading extra installers.

# 1. Enable Corepack shims for your active Node runtime:
corepack enable pnpm

# 2. Prepare and activate the latest stable release:
corepack prepare pnpm@latest --activate

# 3. Verify immediate availability:
which pnpm
pnpm --version

Step 2: Official Standalone Installer & Shell Profile Sourcing

If Corepack is not available or you are on Node.js 22+ where Corepack was decoupled, install pnpm using the official standalone script.

# On Linux & macOS:
curl -fsSL https://get.pnpm.io/install.sh | sh -

# Ensure PNPM_HOME is loaded into your active shell (~/.bashrc or ~/.zshrc):
export PNPM_HOME="$HOME/.local/share/pnpm"
case ":$PATH:" in
  *":$PNPM_HOME:"*) ;;
  *) export PATH="$PNPM_HOME:$PATH" ;;
esac

# Reload your shell profile:
source ~/.zshrc  # or source ~/.bashrc

# On Windows (PowerShell as Administrator):
# iwr https://get.pnpm.io/install.ps1 -useb | iex

Step 3: Alternative Package Manager & CI/CD Configurations

Install pnpm via Homebrew on macOS, globally via npm, or configure official GitHub Actions steps in CI/CD pipelines.

# Option A: On macOS using Homebrew:
brew install pnpm

# Option B: Global installation via npm:
npm install -g pnpm@latest

# Option C: In GitHub Actions CI/CD workflows (.github/workflows/ci.yml):
# - uses: pnpm/action-setup@v4
#   with:
#     version: 9
# - uses: actions/setup-node@v4
#   with:
#     node-version: 20
#     cache: 'pnpm'
# - run: pnpm install --frozen-lockfile

Verification & Testing Steps

Confirm that your shell resolves the pnpm executable path and that dependency management functions normally.

# 1. Inspect the binary location of pnpm:
which pnpm

# 2. Output the active pnpm version:
pnpm --version

# 3. Test installing a dependency in a temporary test directory:
mkdir -p /tmp/pnpm-test && cd /tmp/pnpm-test
pnpm init
pnpm add is-even
pnpm list

Summary Comparison Table

Installation Method	Command / Source	Node.js Dependency	Recommended Scenario
Corepack Activation	corepack enable pnpm	Requires Node.js 16.9+	Fastest setup on standard Node environments
Standalone Script	curl -fsSL https://get.pnpm.io/install.sh | sh -	Standalone (Installs Node if needed)	Linux servers, Docker containers & developers without Node
Homebrew	brew install pnpm	Managed by Homebrew	macOS local development workstations
Global NPM	npm install -g pnpm	Requires existing NPM	Quick fallback when npm is already available