Executing terminal utilities, developer compilers, or package managers in macOS often fails with the shell error: zsh: command not found: [command_name]. Whether you are attempting to run standard tools like brew, node, python, git, or custom command-line utilities, Z shell (zsh) refuses execution. Because Apple transitioned macOS from Bash to Zsh as the default login shell starting with macOS Catalina, older scripts and user profile files that configure system search paths often fail to load properly, preventing the shell from discovering installed binaries.
Resolving ‘zsh: command not found’ requires understanding how Zsh searches directory trees, locating installed binaries, and updating your .zshrc configuration file with complete PATH environment variables.
Why Does Zsh Return ‘command not found’?
When you type a command into the terminal, Zsh does not scan your entire hard drive. Instead, it queries a list of colon-separated directories specified inside the system PATH variable. The command fails due to several standard environment issues:
- Binary Directory Missing from PATH: The package installer placed the executable inside a dedicated directory (such as
/opt/homebrew/binor~/.nvm/versions) that has not been appended to your active Zsh session environment. - Apple Silicon vs Intel Architecture Transition: Homebrew installs binaries into
/opt/homebrew/binon Apple Silicon (M1/M2/M3/M4) Macs, whereas legacy Intel Macs installed them into/usr/local/bin. Migrating to a newer Mac often leaves shell profiles looking in the obsolete Intel directory. - Missing or Unlinked .zshrc File: User path definitions were written to legacy Bash configuration files (
.bash_profileor.bashrc), which Zsh ignores by default upon terminal startup. - Software Not Installed: The developer command-line tools or application packages were never installed or were removed during a macOS operating system upgrade.
Step 1: Check If the Software Is Actually Installed
Verify whether the binary exists on your file system by checking common installation paths:
- Open Terminal.
- Run a targeted file search for the missing utility (replace brew with your affected command):
which -a brew || find /opt/homebrew/bin /usr/local/bin -name "brew" 2>/dev/null - If the command returns a valid filepath (such as
/opt/homebrew/bin/brew), the software is successfully installed, and your shell simply needs an updated PATH pointer. - If no path is found, the software is absent. Install Apple Developer Command Line Tools by running:
xcode-select --install
Step 2: Add Homebrew and Developer Paths to .zshrc
Ensure that standard package locations are loaded whenever Terminal launches:
- Open your user
.zshrcfile in the nano editor:nano ~/.zshrc - Scroll to the bottom of the file and paste the comprehensive standard macOS developer path definition:
# Standard macOS, Apple Silicon Homebrew, and Local Binaries PATH export PATH="/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" # Homebrew shell environment initialization for Apple Silicon if [ -f /opt/homebrew/bin/brew ]; then eval "$(/opt/homebrew/bin/brew shellenv)" fi - Save the file by pressing Ctrl + O and Enter. Exit nano by pressing Ctrl + X.
- Reload the configuration into your active shell session immediately:
source ~/.zshrc - Test your command again (e.g.,
brew --versionornode -v).
Step 3: Migrate Settings from Legacy .bash_profile
If you migrated to a new Mac and previously configured your environment in Bash:
- Inspect whether an existing Bash profile exists:
cat ~/.bash_profile 2>/dev/null || cat ~/.bashrc 2>/dev/null - If this outputs custom paths or tool initializers (such as NVM, Pyenv, or Rust Cargo), append those contents directly into your Zsh profile:
cat ~/.bash_profile >> ~/.zshrc source ~/.zshrc
Step 4: Verify Command Execution in Fresh Terminal Window
To confirm that your changes are permanent:
- Close Terminal completely (Command + Q) and reopen it.
- Print your active search paths by running
echo $PATH. - Verify that
/opt/homebrew/binand/usr/local/binappear at the start of the string. Your commands will now execute reliably across all future terminal sessions.