Check and add the module search path with sys.path in Python

Modified: | Tags: Python

In Python, the module search path is a list of directories that are searched when importing modules and packages using import. This search path is stored in sys.path.

This article describes how to check the current module search paths and add new ones.

See the following article for basic usage of import.

Check the module search path with sys.path

The current module search path is stored in sys.path.

sys.path is a list of strings specifying the module search path. You can view these paths using print().

In this example, pprint is used to make it easier to read.

import sys
import pprint

pprint.pprint(sys.path)

The output should look similar to this:

pwd
# /Users/mbp/Documents/my-project/python-snippets/notebook

python3 print_sys_path.py
# ['/Users/mbp/Documents/my-project/python-snippets/notebook',
#  '/Users/mbp/Documents/lib',
#  '/Users/mbp/Documents/my-project/python-snippets/notebook',
#  '/usr/local/Cellar/python/3.7.0/Frameworks/Python.framework/Versions/3.7/lib/python37.zip',
#  '/usr/local/Cellar/python/3.7.0/Frameworks/Python.framework/Versions/3.7/lib/python3.7',
#  '/usr/local/Cellar/python/3.7.0/Frameworks/Python.framework/Versions/3.7/lib/python3.7/lib-dynload',
#  '/usr/local/lib/python3.7/site-packages']

Keep in mind that the result will depend on your environment. In the example environment with Python3 installed by Homebrew on a Mac, the following directories are stored in sys.path.

  1. The directory containing the executed script file (.py)
  2. The directory set by the environment variable PYTHONPATH (more on this later)
  3. The current working directory
  4. Three directories for the standard library
  5. The site-packages directory for third-party libraries installed with pip

If you change your current directory in the terminal and execute the script again, 3. current directory will be updated to this new path.

cd ..

pwd
# /Users/mbp/Documents/my-project/python-snippets

python3 notebook/print_sys_path.py
# ['/Users/mbp/Documents/my-project/python-snippets/notebook',
#  '/Users/mbp/Documents/lib',
#  '/Users/mbp/Documents/my-project/python-snippets',
#  '/usr/local/Cellar/python/3.7.0/Frameworks/Python.framework/Versions/3.7/lib/python37.zip',
#  '/usr/local/Cellar/python/3.7.0/Frameworks/Python.framework/Versions/3.7/lib/python3.7',
#  '/usr/local/Cellar/python/3.7.0/Frameworks/Python.framework/Versions/3.7/lib/python3.7/lib-dynload',
#  '/usr/local/lib/python3.7/site-packages']

Since the module search path changes depending on the current directory, the import may fail depending on where the script file is executed.

Modules are searched in the order listed in sys.path. Thus, modules in the directory of the currently executed script file (.py) are searched first. Be aware that if there is a file with the same name as a standard library in the same directory as the executed script file, Python will import that file instead.

Add new module search path with sys.path.append()

Since sys.path is essentially a list, you can easily add new paths. In this example, the append() method is used, but you can also use the insert() method or other list methods.

After adding a path to sys.path, you can import modules from the added path.

For example, if you want to add a directory one level above the script file, you can do it like this:

import os
import sys

sys.path.append(os.path.join(os.path.dirname(__file__), '..'))

Remember, adding to sys.path will only affect the current session. If you want to permanently add paths, you can use PYTHONPATH or .pth files, as explained below.

Add new module search path with PYTHONPATH

You can use the environment variable PYTHONPATH to permanently add a module search path.

For Unix-like OS, including Mac, add the following line to ~/.bashrc, for example. To specify multiple paths, separate them with a colon :.

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

For Windows, you can add PYTHONPATH to your environment variables in the same way you would add any other variable: right-click on your PC (My Computer) -> System -> System Properties -> Environment Variables. In Windows, separate multiple paths with a semicolon ;.

In the above example, the directory '/Users/mbp/Documents/lib' is added to the PYTHONPATH.

Add new module search path with path configuration file (.pth)

You can also add module search paths by creating a path configuration file (.pth) in the site-packages directory.

The path configuration file (.pth) should contain one path per line. These paths can be relative or absolute. You can also include comments with #. The file can be named anything as long as the extension is .pth.

Related Categories

Related Articles