How to add a directory to your PATH

I installed a new command-line tool the other day. The instructions said to add its directory to my PATH.

I remember this being confusing. You edit a file, but which one? And what do you add? If you get it wrong, you might even break some of your existing commands.

So let's look at how the PATH works and how to change it safely.

What is the PATH?¶

When you type a command like ls or grep, your shell needs to find the program to run. The PATH is a list of directories that the shell searches through, in order.

It's just an environment variable. A list of directories, separated by colons.

Wait, but why is this necessary? Why doesn't the shell just look everywhere? Searching your whole computer for ls every time would be very slow. The PATH makes it fast.

How to see your PATH¶

You can see what's in your PATH right now by running this command:

echo $PATH

The output will look something like this. It's a mess!

/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

Each entry is a directory path, and they're separated by a colon (:). When you run a command, the shell looks in /usr/local/bin first, then /usr/bin, then /bin, and so on, until it finds a matching program.

First, find your shell¶

The instructions for changing your PATH depend on which shell you're using. The most common are Bash, Zsh, and Fish.

You can find out which shell you're running with this command:

ps -p $$ -o pid,comm=

The output will show you the name of the running program. For me, it's zsh.

  PID COMM
23402 zsh

Now we know which instructions to follow.

How to add a directory to your PATH¶

Let's say I have a directory with my own programs, $HOME/bin, and I want to add it to my PATH.

I want the shell to look in my directory first. This lets me override system commands if I need to, or just make sure my new tools are found before any others. To do this, I need to put my new directory at the beginning of the PATH string.

The pattern is export PATH="<new_directory>:$PATH".

A temporary change¶

You can change the PATH for just your current terminal session. This is a great way to test things out without breaking anything.

export PATH="$HOME/bin:$PATH"

This change will disappear when you close your terminal. It's temporary.

A permanent change (for Bash)¶

For Bash, you should add the export line to your ~/.bashrc file. Some systems use ~/.bash_profile for login shells, but ~/.bashrc is a safe bet for interactive shells.

echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc

This appends the line to the end of your .bashrc file.

A permanent change (for Zsh)¶

For Zsh, the process is almost identical, but the file is ~/.zshrc.

echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc

A permanent change (for Fish)¶

Fish has a slightly different, and I think nicer, way of doing things. It uses a special function. You don't have to edit a file directly.

fish_add_path $HOME/bin

This command modifies a global environment variable, and it prepends the directory by default. It's pretty convenient.

How to check it worked¶

After you've made a permanent change, you'll need to either restart your shell or source the config file (like source ~/.zshrc).

Once you've done that, you can check if your new directory is there.

echo $PATH

You should see $HOME/bin (or the full path to it) at the very beginning of the output.

You can also use which -a to see where a specific command is found. If you have a program named my_script in $HOME/bin, you can run:

which -a my_script

It should show you the path to your script.

Problems you might run into¶

Wrong file: You edit ~/.bashrc but you're using Zsh. Running ps -p $$ helps you get the right shell and edit the right file.
Syntax errors: A missing quote or a typo in the export command can break your PATH. If all your commands suddenly stop working, you might have an empty or broken PATH. You can fix it by running export PATH="/usr/bin:/bin" to get basic commands back, then edit your config file to fix the error.
Changes don't apply: You edited the file, but echo $PATH doesn't show the change. You probably need to open a new terminal or run source ~/.your_config_file.
Duplicate entries: If you run the echo '...' >> ... command multiple times, you'll get the same directory added to your PATH over and over. It's not a huge deal, but it's messy.

A few notes¶

source vs. restarting: Running source ~/.zshrc re-loads the configuration in your current shell. Opening a new terminal does the same thing, but for the new shell.
Installer scripts: Some tools have installers that offer to modify your PATH for you. This is convenient, but it's good to know what they're doing. They're usually just adding a line to your .bashrc or .zshrc.

Changing the PATH used to feel like a mysterious ritual. But it's just a list of directories. Once you know which file to edit for your shell, it gets a lot easier.

— Nadeem