https://docs.python.org/3/using/windows.html#launcher
4.9. Finding modules
Python usually stores its library (and thereby your site-packages folder) in the installation directory. So, if you had installed Python to C:\Python\
, the default library would reside in C:\Python\Lib\
and third-party modules should be stored in C:\Python\Lib\site-packages\
.
To completely override sys.path
, create a ._pth
file with the same name as the DLL (python37._pth
) or the executable (python._pth
) and specify one line for each path to add to sys.path
. The file based on the DLL name overrides the one based on the executable, which allows paths to be restricted for any program loading the runtime if desired.
When the file exists, all registry and environment variables are ignored, isolated mode is enabled, and site
is not imported unless one line in the file specifies import site
. Blank paths and lines starting with #
are ignored. Each path may be absolute or relative to the location of the file. Import statements other than to site
are not permitted, and arbitrary code cannot be specified.
Note that .pth
files (without leading underscore) will be processed normally by the site
module when import site
has been specified.
When no ._pth
file is found, this is how sys.path
is populated on Windows:
- An empty entry is added at the start, which corresponds to the current directory.
- If the environment variable
PYTHONPATH
exists, as described in Environment variables, its entries are added next. Note that on Windows, paths in this variable must be separated by semicolons, to distinguish them from the colon used in drive identifiers (C:\
etc.). - Additional “application paths” can be added in the registry as subkeys of
\SOFTWARE\Python\PythonCore{version}\PythonPath
under both theHKEY_CURRENT_USER
andHKEY_LOCAL_MACHINE
hives. Subkeys which have semicolon-delimited path strings as their default value will cause each path to be added tosys.path
. (Note that all known installers only use HKLM, so HKCU is typically empty.) - If the environment variable
PYTHONHOME
is set, it is assumed as “Python Home”. Otherwise, the path of the main Python executable is used to locate a “landmark file” (eitherLib\os.py
orpythonXY.zip
) to deduce the “Python Home”. If a Python home is found, the relevant sub-directories added tosys.path
(Lib
,plat-win
, etc) are based on that folder. Otherwise, the core Python path is constructed from the PythonPath stored in the registry. - If the Python Home cannot be located, no
PYTHONPATH
is specified in the environment, and no registry entries can be found, a default path with relative entries is used (e.g..\Lib;.\plat-win
, etc).
If a pyvenv.cfg
file is found alongside the main executable or in the directory one level above the executable, the following variations apply:
- If
home
is an absolute path andPYTHONHOME
is not set, this path is used instead of the path to the main executable when deducing the home location.
The end result of all this is:
- When running
python.exe
, or any other .exe in the main Python directory (either an installed version, or directly from the PCbuild directory), the core path is deduced, and the core paths in the registry are ignored. Other “application paths” in the registry are always read. - When Python is hosted in another .exe (different directory, embedded via COM, etc), the “Python Home” will not be deduced, so the core path from the registry is used. Other “application paths” in the registry are always read.
- If Python can’t find its home and there are no registry value (frozen .exe, some very strange installation setup) you get a path with some default, but relative, paths.
For those who want to bundle Python into their application or distribution, the following advice will prevent conflicts with other installations:
- Include a
._pth
file alongside your executable containing the directories to include. This will ignore paths listed in the registry and environment variables, and also ignoresite
unlessimport site
is listed. - If you are loading
python3.dll
orpython37.dll
in your own executable, explicitly callPy_SetPath()
or (at least)Py_SetProgramName()
beforePy_Initialize()
. - Clear and/or overwrite
PYTHONPATH
and setPYTHONHOME
before launchingpython.exe
from your application. - If you cannot use the previous suggestions (for example, you are a distribution that allows people to run
python.exe
directly), ensure that the landmark file (Lib\os.py
) exists in your install directory. (Note that it will not be detected inside a ZIP file, but a correctly named ZIP file will be detected instead.)
These will ensure that the files in a system-wide installation will not take precedence over the copy of the standard library bundled with your application. Otherwise, your users may experience problems using your application. Note that the first suggestion is the best, as the others may still be susceptible to non-standard paths in the registry and user site-packages.
Changed in version 3.6:
- Adds
._pth
file support and removesapplocal
option frompyvenv.cfg
. - Adds
pythonXX.zip
as a potential landmark when directly adjacent to the executable.
Deprecated since version 3.6:
Modules specified in the registry under Modules
(not PythonPath
) may be imported by importlib.machinery.WindowsRegistryFinder
. This finder is enabled on Windows in 3.6.0 and earlier, but may need to be explicitly added to sys.meta_path
in the future.
Categories: Uncategorized