How to fix zsh: command not found error

ZSH is an popular alternative shell which was designed to be an extended version of the Bourne shell. ZSH was chosen to replace Bash and become the default login shell on macOS Catalina and higher. For those of you who didn’t know, the shell is the underlying engine of Terminal.app, where commands are translated into system call.

A common problem for ZSH users is the zsh: command not found error message, which may show up after you’ve made a change to the system. In this article, we will show you a few possible solution to try if you’re encountering “zsh: command not found” on your Mac.

zsh: command not found

“zsh: command not found”, just like many other “command not found” error message, simply indicates that there is no zsh executable file placed in intended system locations, usually /usr/bin or /usr/local/bin. We’ve covered some of the most common ones, namely “pip: command not found”, conda: command not found or “apt-get command not found”.

The error message may show up every time you try to run a command like what’s shown in the image below.

The causes of “zsh: command not found” varies, but there are several common ones on MacOS:

• Incorrect PATH system variable setting.
• Default login shell is set to another value instead of ZSH (on macOS 10.14 Mojave and lower).
• ZSH configuration file points to bash path aliases (.bash_profile)
• iTerm2 shell haven’t been properly configured.

Check PATH system variable setting

Usually, ZSH shell installs its executable named zsh inside common utilities directories. On macOS, those common utilities location includes either /bin, /usr/bin and /usr/local/bin.

The first thing you may want to check is whether you’ve managed to mess up your PATH variable or not. Run the following command to check the current value of PATH :

echo $PATHCode language: PHP (php)

Now try to look for /bin, /usr/bin and /usr/local/bin. If you don’t see one of these, it is very likely that the content of your $PATH is corrupted. Fix it by running the command below, which adds the directories mentioned above back to $PATH.

PATH=/bin:/usr/bin:/usr/local/bin:${PATH}
export PATHCode language: JavaScript (javascript)

Don’t worry about duplicate entries in PATH. macOS, like many other operating system, scans each directory in the PATH list sequentially. Once an executable is found, it stops. So duplicate entries in PATH doesn’t posess any compatibility problem at all.

Alternatively, you can run print $PATH command instead of echo to see the same output.

Reset ZSH

By default, ZSH runs an inititialization script upon installation, which sets up everything including $PATH system variable.

So a faster way to fix zsh: command not found is to run one of the following command. These will re-run the init script and set you up a fresh ZSH installation.

exec /bin/zsh

or

exec /usr/bin/zsh

Set default login shell to ZSH

Like we mentioned earlier, up until before macOS Catalina, the operating system still uses Bash as its default shell.

If you’ve installed and used ZSH on the same Mac before, there are chances that something messed up your system settings and reset that specific option, thus causes “zsh: command not found”. In that case, follow the instructions below to set default login shell to ZSH.

• Open up the Terminal app.
• Select Preferences, select Command (complete path) under Shells open with section. Input /bin/zsh instead of /bin/bash or Default login shell.
• Log out of your Mac and log back in for the changes to take effect.

Alternatively, you can simply run the following command (if you can still access the shell) to fix zsh: command not found.

chsh -s $(which zsh)Code language: JavaScript (javascript)

Running the command above without sudo will make the change for your user only. If you use sudo it will change the shell not only for the current user but also for root.

For those of you who don’t know, chsh is a Linux program used to change your login shell. If a shell is not given on the command line, chsh prompts for one. Please do note that you will only be allowed to change to a shell listed in /etc/shells.

Mixed ZSH and Bash config

One more thing to keep in mind that your ~/.zsh config file should not include any other Bash configuration file. We don’t know why it happens but many users reported that this is the problem in their cases. Follow the instructions below to check your ZSH config file.

• Edit your ZSH configuration file. Usually it should be located in ~/.zsh or ~/.zshrc. If you can’t find those two files, edit /etc/zshrc.
• Check for anything related to Bash and remove those lines. For example, in many cases, removing source ~/.bash_profile inside ~/.zsh fixes the zsh: command not found problem.
• Save the file and reboot the system for the changes to take effect.

Set up iTerm2 shell

iTerm2 is a terminal emulator for macOS which includes support for many nifty features for power users, namely split pane view, paste history, mouseless copy, and many more.

For those of you who are using iTerm2 on a daily basis, changing the system’s default shell with chsh -s $(which zsh) should make the change in iTerm2 as well. But in case it didn’t, follow the instructions below:

• Launch iTerm2.
• Go to Preferences > Profiles > Default.
• Under General tab, enter /bin/zsh in the Command section
• Save the changes and reboot to see whether zsh: command not found error message is gone or not.

We hope that this tutorial provides useful information to help you successfully fix the “zsh: command not found” error message. You might also want to check out our guide on ZSH such as Configure VSCode to work with Zsh or “The default interactive shell is now zsh” message.

If you spot any error in the article, or have a suggestion, please kindly let us know via the comment section below.