The initialization of thesys.path module search path

A module search path is initialized when Python starts. This module search pathmay be accessed atsys.path.

The first entry in the module search path is the directory that contains theinput script, if there is one. Otherwise, the first entry is the currentdirectory, which is the case when executing the interactive shell, a-ccommand, or-m module.

ThePYTHONPATH environment variable is often used to add directoriesto the search path. If this environment variable is found then the contents areadded to the module search path.

Note

PYTHONPATH will affect all installed Python versions/environments.Be wary of setting this in your shell profile or global environment variables.Thesite module offers more nuanced techniques as mentioned below.

The next items added are the directories containing standard Python modules aswell as anyextension modules that these modules depend on. Extensionmodules are.pyd files on Windows and.so files on other platforms. Thedirectory with the platform-independent Python modules is calledprefix.The directory with the extension modules is calledexec_prefix.

ThePYTHONHOME environment variable may be used to set theprefixandexec_prefix locations. Otherwise these directories are found by usingthe Python executable as a starting point and then looking for various ‘landmark’files and directories. Note that any symbolic links are followed so the realPython executable location is used as the search starting point. The Pythonexecutable location is calledhome.

Oncehome is determined, theprefix directory is found by first lookingforpythonmajorversionminorversion.zip (python311.zip). On Windowsthe zip archive is searched for inhome and on Unix the archive is expectedto be inlib. Note that the expected zip archive location is added to themodule search path even if the archive does not exist. If no archive was found,Python on Windows will continue the search forprefix by looking forLib\os.py.Python on Unix will look forlib/pythonmajorversion.minorversion/os.py(lib/python3.11/os.py). On Windowsprefix andexec_prefix are the same,however on other platformslib/pythonmajorversion.minorversion/lib-dynload(lib/python3.11/lib-dynload) is searched for and used as an anchor forexec_prefix. On some platformslib may belib64 or another value,seesys.platlibdir andPYTHONPLATLIBDIR.

Once found,prefix andexec_prefix are available atsys.base_prefix andsys.base_exec_prefix respectively.

IfPYTHONHOME is not set, and apyvenv.cfg file is found alongsidethe main executable, or in its parent directory,sys.prefix andsys.exec_prefix get set to the directory containingpyvenv.cfg,otherwise they are set to the same value assys.base_prefix andsys.base_exec_prefix, respectively.This is used byVirtual Environments.

Finally, thesite module is processed andsite-packages directoriesare added to the module search path. A common way to customize the search path isto createsitecustomize orusercustomize modules as described inthesite module documentation.

Note

Certain command line options may further affect path calculations.See-E,-I,-s and-S for further details.

Changed in version 3.14:sys.prefix andsys.exec_prefix are now set to thepyvenv.cfg directory during the path initialization. This was previouslydone bysite, therefore affected by-S.

Virtual Environments

Virtual environments place apyvenv.cfg file in their prefix, which causessys.prefix andsys.exec_prefix to point to them, instead of thebase installation.

Theprefix andexec_prefix values of the base installation are availableatsys.base_prefix andsys.base_exec_prefix.

As well as being used as a marker to identify virtual environments,pyvenv.cfg may also be used to configure thesite initialization.Please refer tosite’svirtual environments documentation.

Note

PYTHONHOME overrides thepyvenv.cfg detection.

Note

There are other ways how “virtual environments” could be implemented, thisdocumentation refers implementations based on thepyvenv.cfg mechanism,such asvenv. Most virtual environment implementations follow themodel set byvenv, but there may be exotic implementations thatdiverge from it.

_pth files

To completely overridesys.path create a._pth file with the samename as the shared library or executable (python._pth orpython311._pth).The shared library path is always known on Windows, however it may not beavailable on other platforms. In the._pth file specify one line for each pathto add tosys.path. The file based on the shared library name overridesthe one based on the executable, which allows paths to be restricted for anyprogram loading the runtime if desired.

When the file exists, all registry and environment variables are ignored,isolated mode is enabled, andsite is not imported unless one line in thefile specifiesimportsite. Blank paths and lines starting with# areignored. Each path may be absolute or relative to the location of the file.Import statements other than tosite are not permitted, and arbitrary codecannot be specified.

Note that.pth files (without leading underscore) will be processed normallyby thesite module whenimportsite has been specified.

Embedded Python

If Python is embedded within another applicationPy_InitializeFromConfig() andthePyConfig structure can be used to initialize Python. The path specificdetails are described atPython Path Configuration.

See also