"zsh: command not found" on a Mac: why it happens and how to fix it

30 October 2026 · 6 min read

“zsh: command not found: brew” (or whatever name you typed) means the shell looked through every folder on its PATH and found no program with that name. There are three possible reasons: the program isn’t installed, it’s installed in a folder zsh doesn’t search, or the name is wrong. One command, which -a, tells you which of the three you have, and the fix follows from the answer.

What zsh is doing

When you type a command, zsh searches the folders listed in the PATH variable, in order, and runs the first match. If none matches, it prints the error and the name it couldn’t find. zsh has been the default shell on new Macs since macOS Catalina, which is why the message starts with “zsh”.

To see the folders it searches:

echo $PATH

The result is one line, with folders separated by colons.

Find out which case you have

Replace name with the command that failed.

which -a name
type name

which -a lists every match on the PATH. type says how zsh would read the name: a program, an alias, a function or a built-in.

• Nothing found by either. The program isn’t installed, or it’s installed outside the PATH. Look in the likely folder: ls /opt/homebrew/bin for Homebrew on Apple silicon, ls /usr/local/bin on Intel Macs.
• A path comes back but running it still fails. Read the path in the new error. The file may lack permission to run, or it points at something that was deleted.
• It works when you type the full path. That confirms a PATH problem, not an install problem.

Also check the spelling and the case. Commands are case sensitive, and a pasted line sometimes carries a leading $ or a space that the shell reads as part of the name.

Homebrew: “command not found: brew”

Homebrew installs into /opt/homebrew on Apple silicon Macs, and that folder isn’t on the PATH until you add it. The installer ends with a “Next steps” section that gives the commands to do it. In zsh on an Apple silicon Mac they are:

echo >> ~/.zprofile
echo 'eval "$(/opt/homebrew/bin/brew shellenv zsh)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv zsh)"

The first two lines add a blank line and the setup line to the end of ~/.zprofile, creating the file if it’s missing, and the third sets up the current window. Run them once. Homebrew’s own documentation shows the same line without the final zsh, and either form works. If /opt/homebrew/bin/brew doesn’t exist, Homebrew isn’t installed, and the install command on brew.sh is the place to start.

On an Intel Mac, Homebrew’s folder is /usr/local, and /usr/local/bin is already on the default PATH, so “command not found: brew” there usually means it was never installed. Homebrew’s documentation now puts Intel Macs in its lowest support tier and has stopped building new ready-made packages for them, so expect more installs to compile from source.

Python: “command not found: python”

macOS ships python3, not python. Typing python gives the error on a stock Mac, and the fix is to type python3.

Running python3 on a Mac without developer tools opens a prompt instead, saying the python3 command “requires the command line developer tools” and asking “Would you like to install the tools now?” That’s the real macOS installer and the right thing to accept if you want Python. The related error is covered in xcrun: invalid active developer path. If you do want the name python to work, add an alias to ~/.zshrc:

alias python=python3

npm and node

“command not found: npm” or “node” means Node.js isn’t installed, or it was installed by a version manager that hasn’t been started in this shell. Version managers such as nvm add a few lines to ~/.zshrc when you install them, and those lines set up the PATH each time a window opens. If the installer lines are missing from your file, or you edited the file and deleted them, the commands vanish. Run which -a node: if it finds nothing, install Node again or restore the manager’s lines.

“command not found: code”

Visual Studio Code doesn’t add code to the PATH on its own. Open VS Code, press Command-Shift-P to open the Command Palette, type “shell command” and run the command it finds. In current versions with AI features on, it’s called Shell Command: Install ‘code’ and optionally ‘copilot’ commands in PATH; with them off, it keeps the older name Shell Command: Install ‘code’ command in PATH. If it asks about installing the Copilot command too, choosing No adds only code. Then open a new Terminal window.

Edit the right file, then reload it

For a PATH change, ~/.zprofile is read by login shells, which includes the default Terminal window, and ~/.zshrc is read by every interactive shell. Putting PATH lines in ~/.zprofile and aliases in ~/.zshrc is a common split, and either works in Terminal.

To edit either file in Terminal, run nano ~/.zprofile (it creates the file if it doesn’t exist yet). Press Control-O and Return to save, then Control-X to leave. After saving, open a new window, or run:

source ~/.zprofile
rehash

source runs the file in the current window and rehash makes zsh forget its remembered list of commands, so it sees programs installed after the window opened.

What not to do

Don’t use sudo to make the error go away. The error is about where zsh looks, and running something as the administrator won’t change that. And don’t edit /etc/paths for one tool: it needs administrator rights, it changes the PATH for every user, and a line in your own ~/.zprofile does the same job without the risk.

One more case looks like a PATH problem and isn’t: a script in the current folder. zsh never searches the folder you’re in, so myscript.sh fails where ./myscript.sh works. If the script lives somewhere else, open Terminal at a folder first so the ./ form points at it.

Questions

Why does zsh say “command not found” for a program I just installed? The window was already open when you installed it, or the install folder isn’t on the PATH. Open a new Terminal window or run rehash. If that fails, run which -a name and add the folder it should be in to your PATH.

What is the difference between .zprofile and .zshrc? .zprofile is read when a login shell starts, and Terminal opens one by default. .zshrc is read by every interactive shell. Put PATH changes in .zprofile and aliases and prompt settings in .zshrc.

Why is “zsh: command not found: python” an error on a new Mac? macOS doesn’t include a command called python, only python3. Use python3, or add alias python=python3 to .zshrc if you want the shorter name.

How do I see which folders zsh searches? Run echo $PATH. The folders are separated by colons and searched left to right. The first match wins, so the order matters when two versions of a tool are installed.