Source: Mac Path · Command Line Guide · 2024
How to set $PATH in Mac Terminal. Add to the $PATH environment variable in the macOS zsh shell. How to use the Mac $PATH. What goes wrong if you don’t set Mac $PATH.
If you are sure the software you need for a command is installed but you are getting a command not found error, you may be encountering a problem with the $PATH environment variable.
The Mac $PATH is a list of directories (folders) where the computer’s commands and programs are stored for use by the command line, or Terminal. The shell (by default, Zsh, the Z shell) is the program that runs in the Mac Terminal that interprets Unix commands. Shell settings, or environment variables, are stored in configuration files and set when you login or launch the Terminal application. The $PATH variable enables the system to locate the necessary programs without needing the full path for execution.
In this guide, I’ll show how to set the $PATH environment variable so you can run programs you install. For a full explanation about Zsh and setting environment variables, see Shell Configuration.
Before you get started
You’ll need a terminal application to set the $PATH. Apple includes the Mac terminal but I prefer Warp Terminal. Warp is an easy-to-use terminal application, with AI assistance to help you learn and remember terminal commands. Download Warp Terminal now; it’s FREE and worth a try.
If you don’t set the $PATH
If you don’t set the $PATH environment variable, you will encounter these problems:
- Errors such as command not found
- Programs that fail with dependency issues
- Increased manual effort
Explained in detail:
- If you don’t set the Mac
$PATH, the shell won’t be able to locate executable files or commands, particularly programs you’ve added that are not basic shell commands. - Many applications and scripts rely on the
$PATHvariable to find necessary tools or executables. Without a properly set$PATH, these applications will fail. - If you don’t set the Mac
$PATH, you’ll need to specify the full path to an executable every time. This can be tedious and annoying, especially for commands you use frequently.
Viewing the $PATH
You can check the value of the $PATH variable with the echo command:
$ echo $PATH
/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:...
If you have installed Homebrew, the $PATH should contain /opt/homebrew/bin (for Apple M1, M2, or M3) or /usr/local/bin (for macOS Intel). It should be among the highest priority directories, in a left-most position.
When you install a software package, the instructions will often tell you to add a directory to the $PATH variable. Make sure you didn’t overlook the step to add the directory to the $PATH variable.
Typically, the $PATH variable is set in the .zprofile file in your home directory.
How the $PATH works
The $PATH environment variable determines the directories the shell searches for executable files. It’s a list of directory paths, separated by colons (:). For example, a default $PATH looks like /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin.
If you install a new program for use from the command line, you may need to add to the $PATH environment variable. For example, if you install a new program cowsay in the /usr/local/bin directory, $PATH must include the directory or else you’ll need to type /usr/local/bin/cowsay every time you want to run the program. Remember you may not be the only one trying to run the cowsay program: If the cowsay program is called by another program and the $PATH is not set, it won’t be found and the program will fail.
Consider the Homebrew package manager for macOS. It is one of the first tools you’ll need for a local development environment for programming on a Mac. It’s an easy way to install many useful software programs for the terminal, or command line. On Apple silicon (M1, M2, and M2 CPUs), Homebrew installs files into the /opt/homebrew/ folder, which is not part of the default shell $PATH. After you Install Homebrew, you must set the shell $PATH to use any software programs installed by Homebrew.
Where to set the $PATH
Set the $PATH environment variable in the ~/.zprofile (Zsh Profile) file. The tilde ~/ is a Unix abbreviation for your home directory. That is, the .zprofile file belongs in your home directory.
These are the two zsh shell initialization files that are commonly used for configuration:
~/.zshrc(Zsh Run Control): This file is best for adjusting the appearance and behavior of the shell, such as setting command aliases and adjusting the shell prompt.~/.zprofile(Zsh Profile): This file is ideal for commands that should be executed only when the terminal window is opened, such as setting the$PATHenvironment variable.
The article .zshrc or .zprofile explains the differences.
By default, the ~/.zprofile configuration file does not exist for a user on a new Mac. You’ll need to manually create the file in your home directory to properly configure your development environment.
You can create a new file from the command line with the touch command:
$ touch ~/.zprofile
After you create the file, you can edit it.
How to set the $PATH
You can use TextEdit, the default macOS graphical text editor, to edit the shell configuration files. You can open a file in TextEdit from the Mac Terminal:
$ open -e ~/.zprofile
You also can use the command line editors nano or vim to edit the shell configuration files. See Shell Configuration for more about editing shell configuration files.
Decoding the default Mac $PATH
The default $PATH includes the contents of /etc/paths and all the files in the /etc/paths.d directory. On login, maOS uses a utility /usr/libexec/path_helper to set the default $PATH environment variable from the contents of the /etc/paths file and all the files in the /etc/paths.d directory. The path_helper utility is executed at login from /etc/zprofile. It does not duplicate paths, and just appends additional unique values to any existing path.
On old Macs (macOS Mavericks and earlier), the default $PATH was:
/usr/bin:/bin:/usr/sbin:/sbin.
For macOS El Capitan, Sierra, High Sierra, Mojave, and Catalina, the default $PATH was:
/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin.
On macOS Ventura and newer, the default $PATH contains Apple’s cryptexes, a system for applying security patches.
/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin:...(and more, too long to show here).
Directories named bin are for “binaries” or executable command line programs. The sbin directories are for system management programs. The bin and /usr/bin directories are for basic command line programs provided by Apple. The /usr/local/bin is for user-installed executables.
Add to the $PATH
Use a text editor to edit the ~/.zprofile file. The export command sets environment variables in the zsh shell. Here’s the format for setting the $PATH:
export PATH=/path/to/directory:$PATH
The new $PATH variable will be exported to the environment as a combination of the previous $PATH plus a new directory. The new directory comes first; it will take precedence over any directories present in the previous $PATH. A : colon character separates the new directory path from the existing directories in the previous $PATH.
Here’s an example of adding the Homebrew directory used with Apple M1, M2, M3 computers:
export PATH=/opt/homebrew/bin:$PATH
You might see this form with double quotes: export PATH="/opt/homebrew/bin:$PATH" but you won’t need the double quotes unless a directory name contains spaces or special characters.
This example differs from what Homebrew recommends. Homebrew provides its own shellenv utility for setting its path in the ~/.zprofile file. See the article Install Homebrew for details. Here’s what a Homebrew $PATH setting looks like:
eval "$(/opt/homebrew/bin/brew shellenv)"
Reset the shell session
Changes to the ~/.zprofile file will not take effect in the Terminal until you’ve quit and restarted the terminal. Alternatively (this is easier), you can use the source command to reset the shell environment:
$ source ~/.zprofile # Or just restart your terminal
The source command reads and executes a shell script file, in this case resetting the shell environment with your new $PATH setting.
What’s next
My mac.install.guide is a trusted source of installation guides for professional developers. Take a look at the Mac Install Guide home page for tips and trends and see what to install next.