Fixing 'command not found' in zsh on macOS: How to Resolve

What the 'command not found' error means in zsh

The zsh: command not found error occurs when the zsh shell cannot find the executable file for the command you are trying to run. The full error text looks like this:

zsh: command not found: command_name

It appears in the macOS terminal when you enter a command that is either not installed on the system or its path is not listed in the PATH environment variable. This is a common issue when setting up a new Mac or after installing additional tools.

Causes

1. Command not installed — you are trying to run a utility that you haven't added to the system yet (e.g., git, node, docker).
2. Command path missing from PATH — the command is installed, but the directory containing its executable file is not added to the PATH variable.
3. Typo in command name — an accidental error when typing (e.g., gti instead of git).
4. Shell conflict — the command is configured only for bash (via ~/.bash_profile), but not for zsh.
5. Corrupted zsh cache — sometimes zsh does not update the list of available commands after installing new software.

Method 1: Check if the command is installed

First, make sure the command is actually present in your system.

1. Use which or type to search:

   which command_name
   

   
   If the command is found, you will see the full path to the executable file (e.g., /usr/local/bin/git). If not — the command is not installed.
2. Install the command if it's missing:
   • Via Homebrew (recommended):

     brew install package_name
     

   • Via MacPorts:

     sudo port install package_name
     

   • Or download the installer from the official website (e.g., for Git).

Method 2: Check and fix the PATH variable

If the command is installed but which doesn't find it, the issue is with the PATH variable.

1. View your current PATH:

   echo $PATH
   

   
   The output will be a list of directories separated by colons (e.g., /usr/local/bin:/usr/bin:/bin).
2. Find where the command is installed:

   sudo find / -name "command_name" 2>/dev/null
   

   
   This will show all files with that name. Typically, user utilities are stored in /usr/local/bin or ~/bin.
3. Add the missing directory to PATH:
   • Open the zsh configuration file (usually ~/.zshrc):

     nano ~/.zshrc
     

   • Add a line (replace /path/to/directory with the path you found):

     export PATH=$PATH:/path/to/directory
     

   • Save the file (Ctrl+O, Enter, Ctrl+X) and apply the changes:

     source ~/.zshrc
     

4. Verify the command now works:

   which command_name
   

Method 3: Check for typos and case sensitivity

Sometimes the error occurs due to a simple typo. Ensure the command is spelled correctly:

• Case matters: Git ≠ git.
• No extra characters or spaces.
• To verify, use type:

  type command_name
  

  If the command is not found, zsh will show an error. If found, it will display the type (alias, function, builtin, etc.).

Method 4: Reinstall the command via package manager

If the command was installed via Homebrew or MacPorts but stopped working, try reinstalling:

• Homebrew:

  brew reinstall package_name
  brew cleanup  # removes old versions
  

• MacPorts:

  sudo port upgrade package_name
  

After reinstalling, check PATH (Method 2) — sometimes package managers add paths automatically.

Method 5: Update the shell cache

Zsh caches command locations. If you installed a new utility but zsh doesn't see it, refresh the cache:

1. Run rehash:

   rehash
   

   
   This forces an update of the command list.
2. Or restart the terminal — sometimes simply closing and reopening the terminal window is enough.
3. If the problem persists, check for conflicts with configuration files:
   • Ensure there are no errors in ~/.zshrc (you can check with zsh -n ~/.zshrc).
   • Temporarily rename ~/.zshrc (e.g., to ~/.zshrc.backup) and restart zsh. If the error disappears — the issue is in the configuration.

Method 6: Use the full path to the command (temporary workaround)

If you need to run the command urgently while fixing PATH, specify the full path:

/full/path/to/command_name [arguments]

For example:

/usr/local/bin/python3 --version

To find the full path, use which (if the command is installed) or find (see Method 2).

Prevention

To avoid the command not found error in the future:

1. Install commands via Homebrew — it automatically configures PATH for zsh.
2. Check PATH after installing new software — ensure the directory with binaries is added.
3. Use ~/.zshrc for settings — do not edit ~/.bash_profile (it does not affect zsh).
4. Regularly update Homebrew and packages:

   brew update && brew upgrade
   

5. Do not remove system directories from PATH — keep the default values (/usr/bin, /bin, /usr/sbin, /sbin).

If the issue occurs with a specific command, check its documentation — some utilities require additional setup steps.