Python

How to Use Sys.path.append() in Python

Sys.path is a list of directories where the Python interpreter searches for modules. Mind you, this is a list! When a module is claimed in a project file, it will search through each one of the directories in the list. If the module is located within one of those directories, then everything goes fine and your project is successfully rendered. However, if the module is not located within any of the listed directories, then your project will fail lest you can “append” the directory where your module is located to the list using the append() function. In this tutorial, we’ll be learning about how to use sys.path.append() in Python.

List Current Path

By declaring the following, we can check the current Python path:

import sys

from pprint import pprint

pprint(sys.path)

Here, the pprint module is just used to make things look pretty, so you can ignore that part, and concentrate on the rest. All we’re trying to do here is to print out sys.path.

This is what we get:

What you notice here is that first of all, it’s a list. So according to the list, it will first look in the current working directory, then in other directories one by one. The current working directory is the directory in which the main python script – the one being executed – is found. Further, what this also means is that this list can be modified or edited.

Adding a Path

The sys.path.append() method is used specifically to add a Path to the existing ones.

Suppose now that I have two distinct files: main.py, and file1.py. Main.py is the main file, and we’re going to try to import file1.py (a module that we wrote).

main.py file1.py
import file1

print(file1.secret)
secret = “This is the secret phrase”

Because file1.py or our module is within the working directory, you should be able to successfully print out the secret sentence. This is so because when the Python interpreter searches for the requested module, it will search in the working directory first and because our module called file1 is within the working directory, it will automatically print out our secret sentence.

Now, suppose that I create a directory within my working directory called “directory1” and place my module called file1 within it.

Now, within the module file1 is the secret phrase that we’re trying to print out. In this case, it will not print out the secret phrase. Why? Because the interpreter isn’t looking in “directory1” for any modules. In other words, the current working directory is a member of the list of sys.path but “directory1” is not a member of that list. So, the resulting error is a ModuleNotFound Error – it couldn’t find or locate the module called file1.

In order to avert this problem, you need to tell the Python interpreter where to look for the module file1. This is where the sys.path.append() method comes in.

The sys.path.append() method is used to append the path that we want to the existing list.

On a Linux system:

sys.path.append(“/path/to/dir)

On a Windows system, you’d write:

sys.path.append(“C:\\path\\to\\dir)

Please note that you cannot add any given file to sys.path, instead you may add directories, and then import the files you want.

Example #1

So, let’s try the previous operation (where the file1 module is located within directory1) again but this time, we’ll append the path to the file1 module to sys.path using the sys.path.append() method.

main.py file1.py
import sys

sys.path.append(‘C:\\Users\\never\\PycharmProjects\\

pythonProject1\\directory1’)

import file1

print(file1.secret)
secret = “This is the secret phrase”

When we append the path using the sys.path.append() method, we first append the location of the module to Path, and then import it. If done in such a manner, the Python interpreter should be able to locate the requested module, and therefore retrieve the secret variable.

The output of the previous operation is as follows:

Example #2

Let’s take another example, this time on a Linux machine. Let’s suppose that we have one file – main.py.

main.py
import sys

from pprint import pprint

pprint(sys.path)

Here, sys.path[0] is “/home/kalyani” because that is where main.py is located.

Now, let’s modify the script a little bit by using the sys.path.append() method. Let’s use the method to append a particular path (‘/home/kalyani/directory1’) to sys.path.

main.py
import sys

from pprint import pprint

sys.path.append(‘/home/kalyani/directory1’)

pprint(sys.path)

So, the sys.path.append() method has appended the path to the end of the existing list! Here, please also note that the appending is done at the end of the list not at the beginning.

PYTHONPATH

There is one tiny little problem with what we just did and that is that we didn’t permanently put that location onto the sys.path list. The sys.path.append() method is used to temporarily add a path and as such, that path would be valid for a session for example. If you’d like to permanently alter the sys.path list, then we can use PYTHONPATH to add the path to the list. Since sys.path also looks into PYTHONPATH, the locations listed will then be included in the list of paths.

On Linux:

export PYTHONPATH=’/path/to/dir
  1. On your Linux machine, open up a terminal, and navigate to the folder containing .bashrc.
  2. nano .bashrc
  3. Add the following at the end of the .bashrc file:
    export PYTHONPATH=’/home/kalyani/directory1’

Here, you can add the path that you want.

  1. Close the terminal, and open up a new terminal
  2. Now, try executing your program. In my case, it will be the following:
main.py
import sys

from pprint import pprint

pprint(sys.path)

When writing complex programs in Python, we will eventually add third party modules or even better, create our own modules. In all cases, we cannot keep every single Python file we create in one directory, we may wish to use multiple directories to adequately classify our files. The problem however is that we may need to import our created modules left and right. In such cases, if we want to prevent a ModuleNotFound Error, then we can add the location of the directory – and mind you, it has to be a directory, not a file – to sys.path using the sys.path.append() method.

Happy Coding!

About the author

Kalyani Rajalingham

I'm a linux and code lover.