Adding Python Packages to Your System PATH

Content:

When installing python packages using pip, executable packages will be installed into a system folder (such as /usr/local).

If you install packages using the --user option, packages will instead be installed in a folder within your home folder (usually ~/.local/bin).

Unfortunately, these files are unlikely to be executable directly, due to the directory not being specified in the system PATH. This means commands such as

$ pylint

will fail, even though the pylint application is installed.

What Is PATH?

The PATH variable is used by the system to find executable files.

When attempting to run a command in a terminal, the system will search the directories specified in PATH to find the executable the user has entered.

If an executable is found, the program will run.

System executables generally live in /usr/bin, with some residing in /usr/local/bin if installed locally by the system (for example, enabling a SystemD service using the --user flag). Take a look in this directory – you should be able to find executables for some of your installed applications in here.

Directories used by the system are specified by default in the system PATH variable.

To view your current PATH, run echo $PATH.

$ echo $PATH
/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/opt/bin:/usr/lib/llvm/14/bin

Your result will differ slightly depending on the OS you use, but the path should generally contain */bin, */sbin and */lib directories.

Adding the Local Python Folder to PATH

One directory that’s missing from the PATH is the local Python install folder. This means that user-installed Python packages can’t be executed in a terminal – at least, not without specifying the full path each time.

In the following example, the folder containing the executable we want to run is ~/.local/bin.

$ pylint
bash: pylint: command not found

$ ~/.local/bin/pylint
usage: pylint [options]
...

This is rather inconvenient.

To add this path to the system PATH, we can use the export command.

export PATH="path/to/add:$PATH"

It’s recommended to use the variable $HOME, rather than specifying the path to the home folder directly.

~/.local/bin/pylint             # With shorthand home folder path
/home/user/.local/bin/pylint    # Without shorthand
$HOME/.local/bin/pylint         # With $HOME

Be sure to end the PATH string with :$PATH, to append the current PATH variable to the end of the new variable. Without this, the new path will be the only one in the system PATH, which is definitely not what you want to do.

For the above example, the command to run would be

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

Check the PATH again – you should see it has now changed.

$ echo $PATH
/home/user/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/opt/bin:/usr/lib/llvm/14/bin

You should now be able to run executables in the new folder directly.

$ pylint
usage: pylint [options]
...

Unfortunately, this change will only last until the current user session ends.

Making the Change Permanent

To persist this change across user sessions, the directory containing the executable needs to be added to PATH each time the user session begins.

In your home directory, you’ll find a file called .bashrc. The system shell runs this file whenever the user logs in. Each user will have their own .bashrc, found in their home directory.

nano ~/.bashrc

You’ll see some content inside this file, but this can be ignored. Scroll to the bottom of the file, and add the export command used earlier.

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

Save the file, and try logging out. Log back in, and check if the path now shows in your PATH.

$ echo $PATH
/home/user/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/opt/bin:/usr/lib/llvm/14/bin

As the .bashrc runs on every login (including console logins), you’ll now always be able to run executables found in the added directory.