Skip to main content
0 reactions

How to Add a Folder to PATH on macOS (zsh)

Featured card titled Add a Folder to PATH on macOS, showing a folder with a plus sign joining the top of a PATH list that holds ~/scripts, /usr/local/bin, /usr/bin and /bin.
Add a folder to PATH on macOS with one line in ~/.zshrc.

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

SyntaxBash
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 $SHELL in Terminal: /bin/zsh means 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.

TerminalBash
mkdir ~/scripts

Write a two-line script named hello into it:

TerminalBash
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:

TerminalBash
chmod +x ~/scripts/hello

Now try to run it by its name:

TerminalBash
hello
OutputPlain text
zsh: command not found: hello

With its full path, it runs:

TerminalBash
~/scripts/hello
OutputPlain text
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:

TerminalBash
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:

TerminalBash
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

TerminalBash
hello
OutputPlain text
Hello from my scripts folder

To see which file zsh ran, use which:

TerminalBash
which hello
OutputPlain text
/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:

TerminalBash
nano ~/.zshrc

Use the arrow keys to move to the line export PATH="$HOME/scripts:$PATH", then:

  1. Press Control-K to cut the line.
  2. Press Control-O, then Return, to save the file.
  3. Press Control-X to close nano.

Then delete the example folder and its script:

TerminalBash
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:

TerminalBash
hello
OutputPlain text
zsh: command not found: hello

The folder is no longer in PATH.

Common Mistakes

MistakeWhat happensDo this instead
Leaving out :$PATH, as in export PATH="$HOME/scripts"Every other command stops working: zsh: command not found: lsKeep :$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 changeWrite PATH= with no spaces.
~ inside the quotes, as in export PATH="~/scripts:$PATH"zsh: command not found: hello, because zsh doesn’t expand ~ inside quotesWrite $HOME instead of ~.
Adding the script file instead of its folder, as in $HOME/scripts/hellozsh: command not found: helloPATH holds folders. Add the folder the command is in.
Forgetting chmod +xzsh: permission denied: helloRun 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 writtenUse single quotes. Inside double quotes, zsh treats ! as a history command.
Running the echo … >> ~/.zshrc command twiceThe line is in ~/.zshrc twice, and the folder is in PATH twiceIt does no harm, but delete the extra line with nano.

Troubleshooting

ProblemCauseFix
zsh: command not found: hello right after you added the lineThe window was open before the changeRun source ~/.zshrc, or open a new window.
which hello prints hello not foundThe folder isn’t in this window’s PATHCheck the line with grep PATH ~/.zshrc, then run source ~/.zshrc.
Another program with the same name runs instead of yourszsh searches PATH from left to right and runs the first matchwhich -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:

TerminalBash
echo $PATH
Output (the start of the line)Plain text
/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:

~/.zshrcBash
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

0 comments