How to Fix ‘zsh: command not found’ Error in macOS

If you have recently updated your Mac or started using the Terminal for the first time, you might encounter the frustrating zsh: command not found error. Since Apple changed the default shell from Bash to Z shell (zsh) in macOS Catalina, this error has become incredibly common for users trying to run standard command-line tools, Homebrew packages, or custom scripts.

This error occurs when the Z shell cannot locate the executable file for the command you typed. The shell relies on a specific environment variable, known as the PATH, which contains a list of directories to search when you execute a command. If the directory containing your command is not in this PATH, the system will throw the “command not found” error.

Why Does the ‘command not found’ Error Happen?

There are three primary reasons why macOS throws this error:

• Missing or misconfigured PATH: The executable exists, but its directory is not listed in your $PATH variable. This is the most common cause after installing tools like Homebrew, Python, or Node.js.
• Typographical errors: The command was simply misspelt. The terminal is strictly case-sensitive.
• The software is not installed: You are trying to run a command for a program that has not been installed on your system.

How to Temporarily Fix the Error

If you need to run a command immediately without modifying your system configuration, you can specify the absolute path to the executable. For example, if you are trying to run Homebrew but getting the error, you can run it directly from its installation folder.

On Apple Silicon Macs, type:

/opt/homebrew/bin/brew update

On Intel Macs, type:

/usr/local/bin/brew update

While this works for a single session, typing the full path every time is highly inefficient. The better approach is to permanently add the correct directory to your Z shell configuration.

How to Permanently Fix the Error by Updating Your PATH

To permanently resolve the issue, you must add the missing directory to your .zshrc file. This hidden configuration file runs every time you open a new terminal window.

Step 1: Open the .zshrc File

Open your Terminal application and use the nano text editor to open or create your configuration file by typing:

nano ~/.zshrc

Step 2: Add the Export Command

Use your arrow keys to navigate to the bottom of the file. You need to add an export command that appends the missing directory to your existing PATH. For example, to add the standard Homebrew directory on an Apple Silicon Mac, add the following line:

export PATH=$PATH:/opt/homebrew/bin

If you are trying to fix an issue with Python or another tool, replace /opt/homebrew/bin with the correct directory path for that software.

Step 3: Save and Exit

To save your changes in nano, press Ctrl + O (the letter O, not zero), then press Enter to confirm the file name. Finally, press Ctrl + X to exit the editor.

Step 4: Apply the Changes

Your current terminal window does not know about the changes you just made. To apply the new configuration without restarting the Terminal app, use the source command:

source ~/.zshrc

You should now be able to run your commands normally. You can verify that the PATH has been updated successfully by typing echo $PATH and ensuring your new directory appears in the output.