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.prefix andsys.exec_prefix respectively.

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.

Virtual environments

If Python is run in a virtual environment (as described atVirtual Environments and Packages)thenprefix andexec_prefix are specific to the virtual environment.

If apyvenv.cfg file is found alongside the main executable, or in thedirectory one level above the executable, the following variations apply:

  • Ifhome is an absolute path andPYTHONHOME is not set, thispath is used instead of the path to the main executable when deducingprefixandexec_prefix.

_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