Understanding the PATH variable

Photo by Stephen Leonardi on Unsplash

You may have seen a message like the one below when you try to execute a file from the command line:

bash: hello.sh: command not found

What does that mean?

If you tried to search for help online, you may have seen advice to “add the file to the PATH”. This will fix the problem, but what does it mean to add it to the PATH, and should you always do that? In this post, I’ll explain what the PATH is, and how you should use it.

File execution requires the full path

By default, executing any file that you create or download onto your system requires that you specify the full path to that file. This is a safeguard to prevent you from executing something you don’t intend to execute, because anything that executes on your system has the potential to cause damage if it isn’t used correctly.

This is why if you create a program or script, or download one from the internet, and try to execute it with just the executable file name, it doesn’t work, and you see the error shown above.

PATH environment variable

Any operating system (Windows, MacOS, Linux) uses an environment variable called PATH to determine where executable files reside on your system. An environment variable is just a named value that can be referenced by your operating environment. Developers commonly use environment variables to store information used by their applications, but they are also used by the operating system to store and use configuration.

You can see the PATH set on your system by typing the following in a terminal session:

echo $PATH

You should see something like this (the directories listed for you will likely be different):

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

PATH contains a string of directories separated by colons. The way that PATH is used is that any executable files in the directories listed in PATH can be executed without specifying the full path to the file. This allows you to run those executables with only the file name from the command line, or for other applications to run those executables without knowledge of their directory path.

When you type anything on the command line that does not include a directory path, the operating system searches for an executable with that name using the PATH. It starts from the beginning of the PATH, and as soon as it finds an executable file that matches what you typed, it executes that file.

When should I update the PATH?

If you are writing a script or program that will only ever be executed from a single location, you may not need to add it to the PATH. You can just specify the full directory when you execute the file. It is a best practice to keep your PATH variable as clean as you can, with only directories that you or installed applications have designated to be the home of executable files.

If you are creating a script or application that you want to be able to execute without typing the full directory path, for example, if it will be executed from multiple locations (by multiple other scripts or programs) you should first consider moving that file to one of the directories already in your path, or creating a new directory (such as /home/local/bin) to store your script or program file, and add that directory to your PATH.

How do I update the PATH?

To update the PATH temporarily (in the terminal session you are using and only that session), you can just use export from the command line. For example, if you have created a directory called /home/local/bin, and put your executable hello.sh in that directory, you could update the PATH in your current terminal session like this:

export PATH=$PATH:/home/local/bin

Once that is done, you will be able to execute hello.sh without specifying the full path.

If you want to permanently add a directory to your PATH, you will have to update it in one of your system initialisation files, such as your user profile or rc file (i.e., bash_profile, .bashrc — on the latest MacOS, this will be the .zshrc file in your home directory). This file will vary depending on your environment.

At the bottom of the initialisation file for your environment, add the export line shown above and it will permanently update the PATH with your new directory.

It is very important that you include $PATH somewhere in that export statement, usually at the beginning.

If you don’t include the default PATH by including $PATH in your export statement in an initialisation file, you will delete the system directories from the PATH and everything will break!

If this makes you nervous — don’t update your PATH permanently until you understand it well.