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

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/bin or ~/.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/bin on 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_profile or .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:

  1. Open Terminal.
  2. 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
  3. 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.
  4. 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:

  1. Open your user .zshrc file in the nano editor:
    nano ~/.zshrc
  2. 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
  3. Save the file by pressing Ctrl + O and Enter. Exit nano by pressing Ctrl + X.
  4. Reload the configuration into your active shell session immediately:
    source ~/.zshrc
  5. Test your command again (e.g., brew --version or node -v).

Step 3: Migrate Settings from Legacy .bash_profile

If you migrated to a new Mac and previously configured your environment in Bash:

  1. Inspect whether an existing Bash profile exists:
    cat ~/.bash_profile 2>/dev/null || cat ~/.bashrc 2>/dev/null
  2. 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/bin and /usr/local/bin appear at the start of the string. Your commands will now execute reliably across all future terminal sessions.

Get the best tech tips delivered straight to your inbox.

Join thousands of readers mastering Apple, Google, Microsoft, and Linux.