↓ Skip to main content

How to Fix "zsh: command not found: npm" After Node.js Environment Updates

Fixing zsh command not found npm after Node.js environment updates

I opened a fresh terminal tab, typed npm -v, and got this:

zsh: command not found: npm

Odds are your Node install is fine. The shell just can’t see it. You updated Node, switched version managers, or cleaned out old packages, and now a binary that worked yesterday doesn’t exist as far as zsh is concerned. That error means one thing: no directory in $PATH for this particular shell contains a program called npm. Everything below is about working out why, and there are only a handful of reasons.

Why zsh stops seeing npm
#

zsh doesn’t read every config file every time, and that’s where most of this goes wrong. .zshenv is read by every zsh process, scripts included; .zprofile is read by login shells; and .zshrc is read by interactive shells. They run in that order: .zshenv first, then .zprofile if it’s a login shell, then .zshrc if it’s interactive.

Which of those apply depends on where you opened the terminal. macOS terminals open login and interactive shells by default, while Linux terminals usually open non-login interactive ones, so on Linux your ~/.zprofile may never run at all. A PATH line you put there will work on a Mac and do nothing on a Linux desktop. And non-interactive shells skip ~/.zshrc, which is why an editor’s task runner or a git hook can fail with command not found: npm while your own terminal works fine. Your version manager’s init line lives in .zshrc, and those tools never read it.

Then there’s the order. zsh walks $PATH left to right and runs the first match, so whichever init line runs last and prepends to the path wins. That’s why Homebrew’s copy of Node can shadow nvm, or the other way around, depending on which file each tool wrote its line into.

Put those together and you get the usual suspects. The init line isn’t running in this kind of shell. It runs, but no Node version is selected. It points at a directory you deleted. Or Homebrew’s directory is missing from the path, or sitting in front of everything.

Find out where zsh is looking
#

Start by looking at what zsh sees right now:

echo $PATH | tr ':' '\n'
which -a node npm

The first command prints one directory per line. You’re looking for entries pointing at old Node versions that no longer exist, duplicates, and Homebrew’s bin directory sitting ahead of your version manager’s. The second lists every match for node and npm in the order zsh would find them, and the top one is the one that runs. If it prints nothing for npm, no directory on your path has it. That points at an init line that isn’t running, or a version manager with nothing selected.

Read your startup files the way zsh does
#

Search all three for anything touching Node or PATH, in the order they load:

grep -n -E 'nvm|fnm|volta|brew|node|PATH' ~/.zshenv ~/.zprofile ~/.zshrc 2>/dev/null

You should end up with exactly one version manager’s init in there. Two or three overlapping ones is how you get a path that changes depending on which file ran.

One macOS detail trips people up. A utility called path_helper, run from /etc/zprofile, sets the PATH order before ~/.zprofile loads. And because .zshenv is read before /etc/zprofile, a PATH you carefully built in .zshenv can get rearranged before you ever see a prompt. Put your PATH edits in .zprofile or .zshrc and keep .zshenv for the few things non-interactive tools genuinely need.

If you use nvm
#

nvm isn’t a program on your path. It’s a sourced shell function, so if the line that sources it never runs, there’s no nvm and no Node. The installer adds the source lines to your profile file, and .zshrc is the one it picks for zsh. The standard block, normally at the bottom of the file, looks like this:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion

Two nvm-specific traps cause this exact error, and both are easy to miss.

The first is --no-use. People add it to the end of the nvm.sh line to speed up shell startup. That flag postpones using nvm until you run nvm use yourself. Which means every fresh tab starts with nvm loaded and no Node on the path. You’ll get command not found: npm in a brand-new tab and a working npm after you type nvm use. That’s the flag doing what it says.

The second is the default alias. Setting nvm alias default is what chooses the Node version a new shell starts with. If you removed the version it pointed at, or never set one, new shells come up with nothing selected. Check what you’ve got and set one:

nvm ls
nvm alias default 20

Swap 20 for whichever installed version you want. If startup speed is why you added --no-use in the first place, the better fix is a faster manager rather than a half-loaded one.

If you use fnm
#

fnm is built in Rust and starts fast. Setup is a single line in .zshrc that evaluates the output of fnm env.

eval "$(fnm env --use-on-cd --shell zsh)"

--use-on-cd switches versions when you enter a directory with a .node-version or .nvmrc file. Unlike nvm, fnm gives each shell its own directory through the FNM_MULTISHELL_PATH variable, so the path which npm prints sits inside fnm’s own folders and not under Homebrew or /usr/bin. The eval also needs the fnm binary itself on your path. If you installed fnm with Homebrew, make sure Homebrew’s setup runs earlier than this line.

Deal with Homebrew’s copy of Node
#

If Homebrew installed Node at some point, it can sit in front of your version manager. Homebrew links Node into its bin directory, which is /opt/homebrew/bin on Apple Silicon and /usr/local/bin on Intel. The opposite problem happens too: on Apple Silicon, /opt/homebrew/bin isn’t on the default path, and the installer tells you to add eval "$(/opt/homebrew/bin/brew shellenv)" to ~/.zprofile. If that line got deleted in a cleanup, Homebrew’s Node vanishes from your shell.

When you’ve settled on a version manager, take Homebrew’s Node out of the picture. The gentle way is to unlink it, which stops the formula from being on your path. It’s reversible, so you can undo it with brew link node.

brew uses --installed node
brew unlink node

The first command shows whether any other installed formula needs Node. If you’re sure you’re done with it, brew uninstall node removes it for good. Reach for --ignore-dependencies only when that first command came back empty, because the flag removes Node even if something else relies on it.

Reload the right way
#

source ~/.zshrc re-runs your config on top of the environment you already have. Anything a previous source added to the path is still there, plus whatever the new run adds, so duplicates pile up and a fix can look like it worked when it didn’t. A new shell starts from nothing. Open a new tab, or replace the current shell outright:

exec zsh

To test it the way a new macOS Terminal tab would, start a fresh login interactive shell, run one command, and exit:

zsh -ilc 'which -a npm'

You want one line, and it should be a path under your version manager’s own directory: nvm’s folder under your home directory, or fnm’s. If you see /opt/homebrew/bin/npm or /usr/bin/npm on top, something earlier in the path is still winning, and you’re back at the grep.

Keeping it from coming back
#

Pick one manager. Not nvm and fnm and Volta and Homebrew’s Node on the same machine. Every extra one is another init line, another directory on the path, and another chance for load order to flip.

Know which file each line lives in, and stop pasting export PATH= snippets from forum answers without reading what they prepend. Test every change in a fresh shell, not the one you’ve been editing in. If an editor or script still fails while your terminal works, it’s reading a different set of files than you are.

command not found isn’t zsh being broken. It’s zsh telling you the truth: nothing on your path has that name. Go find out why.

Melvin
Author
Melvin
I am a software developer building high-performance local AI tools and web architectures. I created Sablegrid, a platform that automates project scoping end to end. Stellar Tech Labs is where I write up what I learn along the way.

Related

Comments