If Terminal says zsh: command not found for a program you know is on your Mac, the folder it’s in isn’t on your PATH.
PATH is the list of folders that zsh, the shell in the Mac’s Terminal app, searches when you type a command’s name. This guide shows how to add a folder to PATH on macOS for your user account, with one line in a settings file named ~/.zshrc, so it stays there in every new Terminal window and after a restart.
By the end, a small script will run by its name from anywhere, and you’ll be able to add any other folder the same way, such as the bin folder of a tool you installed. Every command and output on this page is real, from zsh 5.9 on macOS.
Syntax
export PATH="<folder>:$PATH"
export: passes the new PATH on to the programs you start from Terminal.PATH: the variable that holds the list of folders zsh searches for commands.<folder>: the full path of the folder to add. For a folder inside your home folder, start it with$HOME, as in$HOME/scripts. Don’t use~here: zsh doesn’t expand it inside quotes.- The colon,
:, separates the folders in the list. $PATH: the folders already in the list, so you keep them. Because your folder comes first, zsh searches it first.- The double quotes keep the whole value together, even when a folder name has a space in it.
PATH and export are described in the zsh manual, under Parameters Used By The Shell (opens in a new tab) and Shell Builtin Commands (opens in a new tab).
Prerequisites
- zsh as your shell. It’s the default for every new user account since macOS 10.15 Catalina, as Apple explains (opens in a new tab). To check, run
echo $SHELLin Terminal:/bin/zshmeans zsh.
Step 1: Make a Folder with a Small Script
To see PATH at work, make a folder with one small script in it. If you already have a folder to add, such as a tool’s bin folder, skip to Step 2 and use its full path instead.
Open Terminal (it’s in Applications › Utilities, or search for it with Spotlight) and make a folder named scripts in your home folder. ~ is short for your home folder.
mkdir ~/scripts
Write a two-line script named hello into it:
echo '#!/bin/zsh' > ~/scripts/hello
echo 'echo "Hello from my scripts folder"' >> ~/scripts/hello
> writes a line into a new file, and >> adds a line to the end of a file. The first line tells macOS to run the file with zsh, and the second prints a message.
Allow the file to run as a program:
chmod +x ~/scripts/hello
Now try to run it by its name:
hello
zsh: command not found: hello
With its full path, it runs:
~/scripts/hello
Hello from my scripts folder
So the script works, but zsh doesn’t look in ~/scripts when you type a name. Adding the folder to PATH fixes that.
Step 2: Add the Folder to PATH in ~/.zshrc
zsh reads a settings file named .zshrc in your home folder every time you open a Terminal window. Add the PATH line to the end of it:
echo 'export PATH="$HOME/scripts:$PATH"' >> ~/.zshrc
>> adds the line to the end of ~/.zshrc, and creates the file if you don’t have one yet. The single quotes save the line exactly as you see it, so $HOME and $PATH are filled in each time a window opens. For your own folder, put its full path in place of $HOME/scripts.
Step 3: Load the Change
A window that was already open still has the old PATH. Load the file into it:
source ~/.zshrc
source runs the commands in a file in the current window. New windows read ~/.zshrc on their own.
Step 4: Run Your Command by Name
hello
Hello from my scripts folder
To see which file zsh ran, use which:
which hello
/Users/user/scripts/hello
Open a new Terminal window with Command-N and run hello there too. It works, because every new window reads ~/.zshrc.
Clean Up: Remove a Folder from PATH
To take a folder out of PATH, delete its line from ~/.zshrc. Open the file in nano, a simple text editor that runs in Terminal:
nano ~/.zshrc
Use the arrow keys to move to the line export PATH="$HOME/scripts:$PATH", then:
- Press Control-K to cut the line.
- Press Control-O, then Return, to save the file.
- Press Control-X to close nano.
Then delete the example folder and its script:
rm -r ~/scripts
Warning: rm -r deletes the folder and everything in it straight away. It doesn’t go to the Trash, so check the folder name before you press Return.
Open a new Terminal window and try the command again:
hello
zsh: command not found: hello
The folder is no longer in PATH.
Common Mistakes
| Mistake | What happens | Do this instead |
|---|---|---|
Leaving out :$PATH, as in export PATH="$HOME/scripts" | Every other command stops working: zsh: command not found: ls | Keep :$PATH at the end. If the line is already in ~/.zshrc, open the file with nano’s full path, /usr/bin/nano ~/.zshrc, and fix it. |
Spaces around =, as in export PATH = "$HOME/scripts:$PATH" | zsh: bad assignment, and PATH doesn’t change | Write PATH= with no spaces. |
~ inside the quotes, as in export PATH="~/scripts:$PATH" | zsh: command not found: hello, because zsh doesn’t expand ~ inside quotes | Write $HOME instead of ~. |
Adding the script file instead of its folder, as in $HOME/scripts/hello | zsh: command not found: hello | PATH holds folders. Add the folder the command is in. |
Forgetting chmod +x | zsh: permission denied: hello | Run chmod +x on the script. |
Double quotes around the first script line, as in echo "#!/bin/zsh" | zsh: event not found: /bin/zsh, and nothing is written | Use single quotes. Inside double quotes, zsh treats ! as a history command. |
Running the echo … >> ~/.zshrc command twice | The line is in ~/.zshrc twice, and the folder is in PATH twice | It does no harm, but delete the extra line with nano. |
Troubleshooting
| Problem | Cause | Fix |
|---|---|---|
zsh: command not found: hello right after you added the line | The window was open before the change | Run source ~/.zshrc, or open a new window. |
which hello prints hello not found | The folder isn’t in this window’s PATH | Check the line with grep PATH ~/.zshrc, then run source ~/.zshrc. |
| Another program with the same name runs instead of yours | zsh searches PATH from left to right and runs the first match | which -a hello lists every match in order. Put your folder before $PATH to search it first. |
FAQ
What is PATH on a Mac?
An environment variable that holds the folders, separated by colons, that your shell searches when you type a command. To see yours:
echo $PATH
/Users/user/scripts:/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin:…
Yours will be different. macOS builds it from the folders in /etc/paths and /etc/paths.d, and some installers add their own folders there.
Should I use ~/.zshrc or ~/.zprofile?
Use ~/.zshrc. zsh reads it in every shell you type into, but reads ~/.zprofile only in login shells. The zsh manual’s startup files section (opens in a new tab) lists which file is read when.
Does the folder stay in PATH after a restart?
Yes. The line lives in ~/.zshrc, and zsh reads that file in every new Terminal window.
How do I add a folder to the end of PATH instead?
In ~/.zshrc, put $PATH first and your folder after it:
export PATH="$PATH:$HOME/scripts"
zsh then searches your folder last, so a command elsewhere in PATH with the same name wins.
How do I add a folder to PATH for every user on the Mac?
macOS builds every user’s PATH from /etc/paths and the files in /etc/paths.d, as man path_helper explains. Changing them needs an administrator password and affects every account on the Mac. For your own account, ~/.zshrc is enough.
What if my shell is bash?
Put the same line in ~/.bash_profile instead. bash reads that file when Terminal opens a window, as the Bash manual (opens in a new tab) describes. Accounts created on macOS 10.14 or earlier can still use bash.
Conclusion
To add a folder to PATH on macOS, add export PATH="<folder>:$PATH" to ~/.zshrc, then run source ~/.zshrc or open a new window. Write $HOME instead of ~, keep :$PATH at the end, and check the result with which.
Additional Resources
- Apple Support: Use zsh as the default shell on Mac (opens in a new tab)
- zsh manual: Startup/Shutdown Files (opens in a new tab)
- zsh manual: Parameters Used By The Shell (opens in a new tab)
- zsh manual: Shell Builtin Commands (opens in a new tab)
- GNU Bash manual: Bash Startup Files (opens in a new tab)
0 comments