How Does Python Find Installed Packages?

The quick answer is that it creates a list of places to search. The resulting list is sys.path. For example:

> python
Python 3.9.1 (default, Jul 13 2024, 10:31:12) 
[Clang 13.0.0 (clang-1300.0.29.3)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys.path
['', '/Users/brent/.pyenv/versions/3.9.1/Library/Frameworks/Python.framework/Versions/3.9/lib/python39.zip', '/Users/brent/.pyenv/versions/3.9.1/Library/Frameworks/Python.framework/Versions/3.9/lib/python3.9', '/Users/brent/.pyenv/versions/3.9.1/lib/python3.9/lib-dynload', '/Users/brent/coding/test/.venv/lib/python3.9/site-packages']

If you need to add a package so it can be found by Python, see How to Add a Package so Python Can Find it.

The Three Parts of sys.path

sys.path is made up of three parts:

1. The initialization path
2. The PYTHONPATH
3. Installation-dependent default paths

1. The Initialization Path

This is a path that is prepended before anything else. It varies depending on how Python was run:

• If you run python -m module  from the command line, it will prepend the current working directory.
• If you run python script.py from the command line, it will prepend the script’s directory.
  • If it’s a symbolic link, it will resolve symbolic links.
• If you run python -c code or python from the command line, it will prepend an empty string (which means the current working directory).

2. The PYTHONPATH

PYTHONPATH is an environment variable that lists one or more paths separated by the system’s path separator. On Windows, it is a semicolon (“;”). On Unix or Mac, it is a colon (“:”). For example:

On Windows:

C:\Python27\Lib;C:\Python27\DLLs;C:\Python27\Lib\lib-tk

On Unix:

:/usr/local/lib/python3.5/dist-packages:/usr/local/lib/python2.7/dist-packages:/usr/local/lib/python3.6/dist-packages

Note: Mac, Windows, or Unix might not have PYTHONPATH already set. This means sys.path is just made up of the initialization path and the installation-dependent default paths. Even if it is empty, you can still set the PYTHONPATH.

3. The Installation-Dependent Default Paths

Your installation of Python will add a default set of paths to sys.path.

How to Add a Package so Python Can Find it

You just need to add it to your PYTHONPATH.

Windows

On Windows, to temporarily set it for your command prompt:

set PYTHONPATH=C:\path\to\your\python\package;%PYTHONPATH%

This will be only for your current command prompt, and will not affect other command prompts.

To permanently set it:

1. Open your Start menu and
2. Search for “Environment Variables”.
3. Click on “Edit the system environment variables”.
4. Click on the “Environment Variables”.
5. If PYTHONPATH does not already exist:
   • Under “System Variables”, click on “New” to add a new environment variable using PYTHONPATH as the variable name and your path for the variable value.
6. If PYTHONPATH already exists:
   • Update it to include your path.
7. Click “OK” to save the environment variable.

You may need to reopen command prompts to see the result.

Mac

On a Mac, to temporarily set it for your terminal:

export PYTHONPATH=/path/to/your/python/package:$PYTHONPATH

Change /path/to/your/python/package to be the path to your package. This will be only for your current terminal, and will not affect other terminals.

To permanently set it, you will need to edit your bash_profile. Open up ~/.bash_profile in your favorite editor, and add the same line you did above to temporarily change the PYTHONPATH.

This will then affect all new terminals that you open.