Fix 'sh: command not found: npm' on macOS and Linux

When you encounter sh: command not found: npm in your terminal, it means your shell cannot locate the npm executable. This error typically appears when Node.js isn’t installed, npm is missing from your system’s PATH, or your shell configuration needs updating. Here’s how to diagnose and fix this common Node.js troubleshooting issue on macOS and Linux systems.

Understanding the npm PATH Error

The error occurs because your shell searches for commands in directories listed in the PATH environment variable. When npm isn’t in any of those directories, you get the sh: command not found: npm message. This happens in three scenarios: Node.js was never installed, the installation failed partially, or your PATH configuration is incorrect.

Quick Diagnosis: Check Your Current Setup

First, verify if Node.js is installed:

node --version

If Node.js is installed but npm isn’t working, check if npm exists on your system:

which npm

No output means npm isn’t in your PATH. Next, examine your current PATH configuration:

echo $PATH

This shows all directories your shell searches for commands. If npm’s directory isn’t listed, that’s your problem.

Installing Node.js and npm on macOS

Using Homebrew (Recommended)

Homebrew provides the cleanest installation method for macOS:

brew install node

This installs both Node.js and npm, automatically configuring your PATH. Verify the installation:

npm --version

Direct Download Method

Alternatively, download the installer from nodejs.org. The macOS installer handles PATH configuration automatically, but you’ll need to restart your terminal afterward.

Installing Node.js and npm on Linux

Ubuntu/Debian Systems

Use your distribution’s package manager:

sudo apt update
sudo apt install nodejs npm

Fedora/RHEL Systems

sudo dnf install nodejs npm

Arch Linux

sudo pacman -S nodejs npm

After installation, verify npm works:

npm --version

Fixing PATH Configuration Issues

If npm is installed but still showing the error, you need to add it to your PATH manually.

For Bash Users

Edit your .bashrc file:

echo 'export PATH="$PATH:/usr/local/bin"' >> ~/.bashrc
source ~/.bashrc

For Zsh Users (macOS Default)

Edit your .zshrc file:

echo 'export PATH="$PATH:/usr/local/bin"' >> ~/.zshrc
source ~/.zshrc

Replace /usr/local/bin with your actual npm installation path. Find it using:

find / -name npm 2>/dev/null

Using Node Version Manager (nvm)

nvm prevents version conflicts and PATH issues by managing Node.js installations separately from system packages. This approach eliminates most npm command not found errors.

Install nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

Install Node.js via nvm

nvm install node
nvm use node

nvm automatically handles PATH configuration and allows switching between Node.js versions for different projects. It’s particularly useful when working with projects requiring specific Node.js versions.

Shell-Specific Troubleshooting

Different shells may require specific configurations:

• Bash: Check .bashrc or .bash_profile
• Zsh: Check .zshrc
• Fish: Check ~/.config/fish/config.fish

Always restart your terminal or run source on the configuration file after making changes.

Verifying Your Fix

After applying any solution, verify npm works correctly:

npm --version
npm list -g --depth=0

Test installing a package to ensure full functionality:

npm install -g npm@latest

Common Pitfalls to Avoid

Don’t use sudo with npm global installations unless absolutely necessary—it can cause permission issues later. If you encounter permission errors, consider changing npm’s default directory or using npx instead of global installations.

For corporate environments with proxies, configure npm’s proxy settings:

npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

Conclusion

The sh: command not found: npm error is straightforward to fix once you understand its cause. Whether through package managers, direct installation, or nvm, getting npm working involves ensuring Node.js is installed and your PATH is configured correctly. Using nvm provides the most flexible solution, especially for developers managing multiple projects. With npm functioning properly, you can focus on building rather than troubleshooting your development environment.

FAQs

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.