Check and add the module search path with sys.path in 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
.
- The directory containing the executed script file (
.py
) - The directory set by the environment variable
PYTHONPATH
(more on this later) - The current working directory
- Three directories for the standard library
- The
site-packages
directory for third-party libraries installed withpip
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
.