Package Location#

Before we explain how to install additional packages, let’s first investigate where Python looks for packages in order to use them.

When Python imports a module, it basically searches through the directories listed in sys.path. For debugging purposes it can be helpful to inspect the list of folders on your platform.

$ python -c 'import sys; [print(p) for p in sys.path]'

It typically consists of

  • the empty string or the current directory, depending how Python was invoked

  • optional directories from the PYTHONPATH environment variable

  • the directories with the standard library

    • /path-to-python/lib/python311.zip for embeddable installations

    • /path-to-python/lib/python3.11 with Python modules

    • /path-to-python/lib/python3.11/lib-dynload with C extensions

  • the site-packages directory with third-party packages

  • optional directories defined by .pth files

Of particular significance is the site-packages directory. This is where any additional packages are located, that have been installed by pip. Our Linux machines will also include dist-packages folders that are used by the Debian packages.

It’s important to understand that the site-packages location is determined dynamically by the site module. The lookup logic is crucial for virtual environments to work.

For sake of concreteness, let’s consider the example import pandas. Python will loop through the sys.path directories and look for pandas.py or pandas/__init__.py. The first package found with the matching name gets imported. As direct consequence, only a single version of any package can be used. This is why package management and virtual environments are indispensable.

Tip

Most users should avoid “hacking” the PYTHONPATH or sys.path directory lists. We recommend to use proper virtual environments instead.

See also