zsh: command not found — causes and fixes

What the zsh: command not found Error Means

The zsh: command not found error (sometimes with exit code 127) appears when the Zsh shell cannot find the executable file for the specified command in any of the directories listed in the PATH environment variable. The full message typically looks like this:

zsh: command not found: <command_name>

This occurs when you type a command in the terminal and prevents the execution of any scripts or interactive actions that require that utility.

Common Causes

1. The command is not installed — the corresponding package is not present on your system.
2. The directory containing the executable is missing from PATH — the command is installed, but Zsh doesn't know where to look for it (e.g., programs from /snap/bin or /usr/local/bin).
3. Typo in the command name — for example, gti instead of git.
4. Alias or function conflict — an alias with the same name contains an error or redirects to a non-existent file.
5. Corruption or absence of Zsh configuration files (e.g., ~/.zshrc) where PATH is set.
6. The command is installed, but for a different architecture (e.g., a 32-bit binary on a 64-bit system without compatibility support).

Solution 1: Check if the Command is Installed

Verify that the command actually exists on your system. Use the which, type, or command -v utilities:

which git
type python3
command -v docker

If the command is not found, search for the package that provides it:

• For Ubuntu/Debian: apt search <part_of_command_name>
• For Fedora: dnf search <part_of_command_name>
• For Arch Linux: pacman -Ss <part_of_command_name>

Solution 2: Check and Fix the PATH Variable

View your current PATH:

echo $PATH

The output is a colon-separated list of directories. Ensure it includes the path to the executable files for your command (e.g., /usr/bin, /usr/local/bin, /snap/bin). If the required directory is missing:

1. Open ~/.zshrc in an editor (e.g., nano ~/.zshrc).
2. Look for a line with export PATH=.... If it doesn't exist, add this to the end of the file:

   export PATH=$PATH:/additional/directory
   

   
   For example, for Snap packages:

   export PATH=$PATH:/snap/bin
   

3. Save the file and run source ~/.zshrc or restart your terminal.

Solution 3: Install the Missing Command

If the command is not installed, install it using your package manager. Examples:

• Installing Git on Ubuntu/Debian:

  sudo apt update
  sudo apt install git
  

• Installing Docker on Fedora:

  sudo dnf install docker
  

• Installing Python on Arch Linux:

  sudo pacman -S python
  

After installation, verify the command is now available: which git.

Solution 4: Check Aliases and Functions

Sometimes an alias or function named after the command may be defined incorrectly. List them:

alias
functions

If you see an alias for the problematic command (e.g., alias gti='gut'), remove it from ~/.zshrc or correct it. To temporarily bypass an alias, use a backslash: \gti.

Solution 5: Restart the Shell or Open a New Terminal

Sometimes changes to PATH or package installations require restarting Zsh. Run:

exec zsh

or simply close and open a new terminal window.

Prevention

• Regularly update your PATH when installing programs to non-standard directories (e.g., via pip install --user or cargo install).
• Use package managers instead of manually installing binaries to automatically configure PATH.
• Check your ~/.zshrc for typos or conflicting settings.
• Compare PATH in Zsh and bash (echo $PATH in each) if a command works in one shell but not the other.
• Avoid global aliases with names of standard utilities unless you are certain of their correctness.