Claude Code "command not found": 4 causes in diagnostic order

You ran npm install -g @anthropic-ai/claude-code, it completed without errors, but typing claude in your terminal returns zsh: command not found: claude (or the bash equivalent). This is a PATH configuration problem, not an installation failure. The binary is on your system — your shell just doesn't know where to look for it. This page walks through all four causes in the order to check them.

Step 0: Confirm the binary is actually installed

Before fixing PATH, confirm the installation succeeded and the binary exists:

# Find where npm installed the binary
npm config get prefix
# Example output: /Users/yourname/.npm-global  (macOS)
# or: /usr/local  (some Linux setups)

# Check if the binary is there
ls $(npm config get prefix)/bin/claude
# If this shows the file, the install worked — you have a PATH problem.
# If "no such file," the install failed — see the reinstall section below.

Cause 1: npm global bin directory not in PATH

This is the cause in 80%+ of cases. npm installs global binaries to a directory that isn't in the default PATH on many macOS and Linux setups. The installation runs fine, the binary exists, but the shell has no idea where to find it.

Fix:

# Get the npm prefix (the directory containing bin/)
npm config get prefix

# Add to PATH — for zsh (macOS default since Catalina):
echo 'export PATH="'$(npm config get prefix)'/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Add to PATH — for bash:
echo 'export PATH="'$(npm config get prefix)'/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Verify it worked:
which claude
# Should output a path like /Users/yourname/.npm-global/bin/claude

If you're not sure which shell you're using: echo $SHELL. Output ending in zsh means use ~/.zshrc; bash means use ~/.bashrc or ~/.bash_profile on macOS.

Cause 2: Node.js version too old

Claude Code requires Node.js 18 or later. If your system has an older version, the npm install command may appear to succeed but the binary may fail to run or not be created at all.

# Check your Node version:
node --version
# Must be v18.0.0 or higher

# If too old, update with nvm (recommended):
nvm install --lts
nvm use --lts
nvm alias default node   # Set new version as default

# Then reinstall Claude Code:
npm install -g @anthropic-ai/claude-code

# Or without nvm, download from nodejs.org and reinstall.

Cause 3: Shell config not reloaded in existing windows

If you already fixed your PATH in ~/.zshrc or ~/.bashrc but claude still says "command not found" in existing terminal windows — those windows loaded the old config at startup and don't automatically pick up changes.

Fix:

# Reload config in the current terminal window:
source ~/.zshrc    # for zsh
# or
source ~/.bashrc   # for bash

# New terminal windows opened after the config change will work automatically.

This is the cause when claude works in a newly opened terminal but not in older ones.

Cause 4: Using nvm — global packages are per Node version

If you manage Node with nvm, each Node version has its own global package store. Installing Claude Code while Node 18 is active means it's only available when Node 18 is the active version. Switch to Node 20 and it's gone.

# Check your active version:
nvm current

# Check which version you installed Claude Code under:
nvm list   # Look at which version has claude in its globals

# Fix — install Claude Code for the version you want to use:
nvm use 20   # or whatever version you're targeting
npm install -g @anthropic-ai/claude-code

# Verify:
claude --version

Alternatively, use nvm alias default to set a consistent default Node version so global packages are stable across sessions.

If the binary doesn't exist after install (reinstall)

If ls $(npm config get prefix)/bin/claude shows "no such file," the installation failed silently. This usually means a permission error during install or a network timeout.

# Clear npm cache and reinstall:
npm cache clean --force
npm install -g @anthropic-ai/claude-code

# If you get EACCES permission errors on the global directory:
# DO NOT use sudo with npm — instead, fix the npm prefix:
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
# Then add ~/.npm-global/bin to PATH (Cause 1 fix above)
# Then reinstall:
npm install -g @anthropic-ai/claude-code

Full working install from scratch (macOS/Linux)

# 1. Install or update Node to v18+ via nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.zshrc   # or ~/.bashrc
nvm install --lts
nvm use --lts

# 2. Set a safe npm global prefix:
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 3. Install Claude Code:
npm install -g @anthropic-ai/claude-code

# 4. Verify:
claude --version

FAQ

Should I install Claude Code with sudo? No. Using sudo npm install -g installs to a root-owned directory, which causes permission errors on future updates and is a security risk. Set up a user-owned npm prefix as shown above instead.

Claude Code installed fine on my desktop but not my work laptop. Why? Work laptops often have IT-managed Node installs (older versions), restricted npm prefix directories, or proxy settings that prevent npm from downloading packages. Check node --version first, then verify npm can reach the registry: npm ping.

I fixed PATH but 'claude --version' shows an error about missing dependencies. This means the package installed but a native dependency failed to compile. Try npm install -g @anthropic-ai/claude-code --force after confirming your Node version is 18+.

Related

• Claude Code permission denied: what it means & how to fix it
• Claude API 401 authentication_error: 5 causes & fixes
• How to use Anthropic prompt caching to cut API costs

Last updated June 2026. Verified against Claude Code CLI current release and Node.js 18/20 LTS.