Engineer How-To: Access & Make Awesome Your PATH System Variable

"Just add this to your PATH, and..."

It can come up in tutorials about almost anything to do with software engineering: a quick, innocuous reference to adding something to your PATH. I first encountered this while trying to make Postgres accessible via the command line: there, early in the tutorial, that one fatal line: “Put the library in the PATH.” I didn’t know what was meant, in that context, by library, and I certainly didn’t know what PATH meant here. And just like that, before I had the chance to create a table, my Postgres installation was stalled.

This need to change or augment your PATH can come up in many contexts, when you’re starting to learn to program, digging into the hidden depths of the faithful computer you felt you knew. Maybe you need to make a program accessible via text command in your terminal. Maybe you were just trying to get Postgres, AWS, or some exciting tool you found on GitHub to work. If you’re a novice, this can be an early roadblock in attempting to work through a tutorial: just add it to your PATH - or perhaps add a directory to PATH, set your PATH, edit your PATH, etc. All red lights if you don’t know what PATH refers to.

Many tutorials attempt to address PATH in a sentence or less, if at all. And, worse, other tutorials (or attempts at them) assume more initial knowledge than a lot of novices have, flinging out disconnected jargon in a well-intended flurry that can push even true believers away from learning this small, vital skill.

Today, we fix that. Join us.

What PATH is, what PATH does

PATH is an environmental variable containing a colon-separated list of directories. It gives your computer direction to match command to program, rather than forcing it to look through every directory on your computer every time you type mkdir, cd, or aws ec2 describe-instances.

Here’s a simple PATH:

PATH=/bin:/usr/bin:/usr/local/bin

That tells your computer to search for a program that matches the command you entered in your terminal, in the following directories and in the following order:

  • /bin

  • /usr/bin

  • /usr/local/bin

If the command you’re trying to use doesn’t match a resource in any of those directories, you’ll get a “command not found” error.

It’s a good practice to list the most frequently used ones first, for efficiency’s sake. If you haven’t altered your machine’s PATH yet, it may still look like the modest one shown above.

But let’s find out for sure.

How to view your PATH

In your terminal, type echo $PATH

There, you’ll see every directory your machine will look in when matching terminal command to program, whether you specified the directory yourself or it was included by default by your OS.

The whole of your PATH can come together in a couple of different ways. Either it’s specified with a single variable assignment, or it’s concatenated from multiple sources.

Doing the latter can get you where you need to go (and provide a more temporary solution for squeamish new arrivals to this whole PATH business), but it can also introduce unnecessary duplication and inefficiency.

Be brave. Set your PATH deliberately and decisively. Here’s how.

Editing your PATH

The first step is figuring out which of several possible files contributes to your PATH, as listed when you echo $PATH in your terminal. Your computer, whether through existing system settings or some not especially well-considered attempt at PATH alteration in your past (no blame, no shame - I’ve been there too), may have multiple files that could affect the PATH. Here they are in the order that your Mac will look at them.

  • ~/.bashrc (read on every new shell, so looked at far more often)

  • ~/.bash_profile (read only on login)

  • ~/.profile

You don’t need more than one, so spare yourself the confusion and consolidate if you do have multiples. If you have a ~/.bash_profile, just copy its contents and add it to ~/.bashrc in a way that makes sense. Then delete the unused file. It feels dramatic, yes, but you’ll be glad later. (And if you want to learn more about these files and the uses and intentions that contribute to the order above, type man bash into your terminal and dive in.)

To edit it in the terminal, type nano ~/.bashrc (or substitute your text editor of choice). There it is: your PATH.

On a Mac, the PATH variable is initially set to /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

To augment this default, add this line to ~/.bashrc (altered with your particular PATH needs):

export PATH=$PATH:/extra/path:/pieces/go/here:/after/the/path:/listed/above

This reestablishes the PATH environmental variable to whatever PATH already is in your system, plus whatever you tack onto the end. This will get you where you need to go - but there’s a more elegant and deliberate way to do it.

Take a look at your current PATH, the one you echoed in your terminal. Scan it, looking for:

  • Duplicated directories

  • Too-specific or rarely used directories up front

  • Anything that looks weird (such as whole PATH pieces dedicated to a single directory for a single program - especially one you use all the time)

Copy it into your text editor of choice and prune, rearrange, and edit until it makes sense. This is a mix of art and science - and also a fun subject to solicit opinions from more experienced engineers about. I find it’s up there with “What’s your least favorite programming language?” so far as learning something new and unexpected.

Most-used directories should go first; less-used toward the end. Your PATH will probably never get too big for your computer to handle, but keeping it as concise as possible is a good practice.

Now, open up ~/.bashrc and add this, replacing any existing PATH-related debris:

export PATH=/bin:/usr/bin:/usr/local/bin:/whatever/else:/you/want:/to/add

You only want one line setting your PATH variable - otherwise, the system will ignore all but the last one anyway, as it will overwrite everything that came before.

Save and close ~/.bashrc. Close your terminal and reopen it. echo $PATH. Beautiful, right?

But what’s the best way to make new programs accessible via the terminal with your newly renovated PATH?

How to use PATH to make new programs accessible in the terminal

It takes two steps to add new programs to your roster of terminal-accessible tools:

  1. Put the program itself in an accessible directory.

  2. Ensure the directory containing your program is listed in your PATH variable.

Makes sense, right? Here’s how to do it.

  1. Decide if you want to really commit to the new program.

    1. Friends for life? Add it to /bin or another directory close to your home directory. /usr/local/bin is another good option.

    2. It’s complicated? Consider keeping those programs in a separate, special directory and either adding it to the end of your existing PATH variable (if only for now) or temporarily adding it in the way discussed in the next section.

    3. To check to see what’s currently in /bin (or any other directory), type ls /bin (or your directory in question) into your terminal. You’ll see all available commands/programs in that directory.

  2. If the directory isn’t currently in your PATH variable (and you want it to be for the foreseeable future), open ~/.bashrc and add the directory to the PATH variable.

  3. Close all your terminal windows and open a new one. All new settings will be in place.

Temporary PATH additions

If you’ve tried to edit your PATH before and only temporarily solved your problem, only to have your solution disappear the next time you started a new terminal session, you might have happened on this next tactic by accident. PATH is an environmental variable, so you can change it or add to it within a terminal session. However, that value will not persist, disappearing into the ether as soon as you close that terminal window and end the session.

It’s irritating when you do it by accident, but useful when you’re trying out a tool and don’t want to commit to throwing it in with your bin-based stalwarts. To temporarily add a directory to your PATH, type this in your terminal: PATH=$PATH:/your/new/tool/directory

This adds that directory to the end of your existing PATH - but only for that terminal session. If you switch to another terminal window or if you close that window and reopen it, your temporary PATH addition will disappear.

PATH TL;DR

Let’s review:

  • PATH is an environmental variable.

  • It’s a colon-separated list of directories where the shell might find programs to match the commands you type into your terminal.

  • You can see your current PATH by typing echo $PATH in your terminal.

  • You can change it for a single session through your terminal or more permanently by using certain system files.

  • You’ll most often need to edit or augment your path when adding new terminal-accessible programs.

And that’s it! You’ve been working alongside PATH values for as long as you’ve used a computer, even if you didn’t know it. Now, when you encounter that nefarious suggestion to just edit your PATH in an otherwise well-meaning tutorial, you can do what you need to in ~/.bash_rc or your terminal and keep on going.

With many thanks to Mark and Nick.