The 'Command Not Found' Headache
You just finished installing a new tool, hit Enter, and instead of a version number, you get the dreaded zsh: command not found. This error is a rite of passage for macOS developers. It usually pops up right after you've set up Node.js, Python, or Flutter, or when you've migrated your data to a new M3 MacBook Pro.
What’s actually going wrong?
Since macOS Catalina, Apple has used Zsh as the default shell. When you type a command, Zsh looks through a specific list of folders to find the executable file. This list is your $PATH. If the folder containing your new tool isn't on that list, Zsh simply gives up. To fix it, we just need to point the terminal in the right direction.
Solution 1: The Permanent Fix via .zshrc
Modifying your .zshrc file is the most reliable method. This script runs every time you launch a new terminal window, ensuring your tools are always ready to go.
Step 1: Find your tool's home
First, identify where your software lives. Here are the 4 most common locations for macOS tools:
- Homebrew (Intel Macs):
/usr/local/bin - Homebrew (Apple Silicon M1/M2/M3):
/opt/homebrew/bin - Flutter SDK:
~/development/flutter/bin - Python 3.12:
~/Library/Python/3.12/bin
Step 2: Open the configuration file
We'll use Nano, a simple text editor built into your terminal. Run this command to open your configuration:
nano ~/.zshrc
Step 3: Update your PATH string
Go to the very bottom of the file. Paste the following line, but make sure to replace the placeholder with the actual path you found in Step 1:
export PATH="$PATH:/your/custom/path"
For instance, if you are setting up Homebrew on a new M2 MacBook Air, your line should look like this:
export PATH="$PATH:/opt/homebrew/bin"
Step 4: Save and exit
Nano uses keyboard shortcuts for saving. Press Ctrl + O and then Enter to write the changes to the disk. Finally, hit Ctrl + X to get back to the main prompt.
Step 5: Force the changes to take effect
Your terminal won't notice the change until you restart it or manually refresh the config. Run this to apply the update instantly:
source ~/.zshrc
Solution 2: The Quick Fix for Homebrew on Apple Silicon
Apple Silicon Macs handle Homebrew differently than older Intel models. If brew is the specific command failing, Homebrew has a built-in way to fix itself. Paste these two lines into your terminal and hit Enter:
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
eval "$(/opt/homebrew/bin/brew shellenv)"
This command appends a specialized initialization script to your .zshrc that handles the PATH logic for you automatically.
Solution 3: The 'Emergency' Recovery
We've all been there: you edit your .zshrc, save it, and suddenly even basic commands like ls or cd stop working. This happens if you accidentally overwrite your PATH instead of adding to it.
Don't panic. You can temporarily restore standard functionality by running this command:
export PATH="/usr/bin:/bin:/usr/sbin:/sbin"
Now that nano works again, open ~/.zshrc and look for your mistake. Ensure you included the $PATH: part in your export line. That little snippet tells Zsh to keep all the existing folders while adding your new one to the end of the list.
Verification: Did it work?
Once you've sourced your file, run a quick check to see the new list of active directories:
echo $PATH
You should see your new path (like /opt/homebrew/bin) at the end of the string. You can also ask the Mac exactly where it sees the tool by typing:
which <command_name>
If it returns a valid file path, you're back in business.
Pro-Tips for a Cleaner Terminal
- Forget .bash_profile: macOS hasn't used Bash as the default since 2019. If you're adding paths to
.bash_profile, they won't show up in Zsh. - Watch for typos: A single missing colon (
:) or an extra space around the=sign will break the entire configuration. - The 'Nuclear' Option: If
source ~/.zshrcfeels buggy, completely quit the Terminal app withCmd + Qand restart it. This forces a clean environment load.