1.. _sys-path-init: 2 3The initialization of the :data:`sys.path` module search path 4============================================================= 5 6A module search path is initialized when Python starts. This module search path 7may be accessed at :data:`sys.path`. 8 9The first entry in the module search path is the directory that contains the 10input script, if there is one. Otherwise, the first entry is the current 11directory, which is the case when executing the interactive shell, a :option:`-c` 12command, or :option:`-m` module. 13 14The :envvar:`PYTHONPATH` environment variable is often used to add directories 15to the search path. If this environment variable is found then the contents are 16added to the module search path. 17 18.. note:: 19 20 :envvar:`PYTHONPATH` will affect all installed Python versions/environments. 21 Be wary of setting this in your shell profile or global environment variables. 22 The :mod:`site` module offers more nuanced techniques as mentioned below. 23 24The next items added are the directories containing standard Python modules as 25well as any :term:`extension module`\s that these modules depend on. Extension 26modules are ``.pyd`` files on Windows and ``.so`` files on other platforms. The 27directory with the platform-independent Python modules is called ``prefix``. 28The directory with the extension modules is called ``exec_prefix``. 29 30The :envvar:`PYTHONHOME` environment variable may be used to set the ``prefix`` 31and ``exec_prefix`` locations. Otherwise these directories are found by using 32the Python executable as a starting point and then looking for various 'landmark' 33files and directories. Note that any symbolic links are followed so the real 34Python executable location is used as the search starting point. The Python 35executable location is called ``home``. 36 37Once ``home`` is determined, the ``prefix`` directory is found by first looking 38for :file:`python{majorversion}{minorversion}.zip` (``python311.zip``). On Windows 39the zip archive is searched for in ``home`` and on Unix the archive is expected 40to be in :file:`lib`. Note that the expected zip archive location is added to the 41module search path even if the archive does not exist. If no archive was found, 42Python on Windows will continue the search for ``prefix`` by looking for :file:`Lib\\os.py`. 43Python on Unix will look for :file:`lib/python{majorversion}.{minorversion}/os.py` 44(``lib/python3.11/os.py``). On Windows ``prefix`` and ``exec_prefix`` are the same, 45however on other platforms :file:`lib/python{majorversion}.{minorversion}/lib-dynload` 46(``lib/python3.11/lib-dynload``) is searched for and used as an anchor for 47``exec_prefix``. On some platforms :file:`lib` may be :file:`lib64` or another value, 48see :data:`sys.platlibdir` and :envvar:`PYTHONPLATLIBDIR`. 49 50Once found, ``prefix`` and ``exec_prefix`` are available at :data:`sys.prefix` and 51:data:`sys.exec_prefix` respectively. 52 53Finally, the :mod:`site` module is processed and :file:`site-packages` directories 54are added to the module search path. A common way to customize the search path is 55to create :mod:`sitecustomize` or :mod:`usercustomize` modules as described in 56the :mod:`site` module documentation. 57 58.. note:: 59 60 Certain command line options may further affect path calculations. 61 See :option:`-E`, :option:`-I`, :option:`-s` and :option:`-S` for further details. 62 63Virtual environments 64-------------------- 65 66If Python is run in a virtual environment (as described at :ref:`tut-venv`) 67then ``prefix`` and ``exec_prefix`` are specific to the virtual environment. 68 69If a ``pyvenv.cfg`` file is found alongside the main executable, or in the 70directory one level above the executable, the following variations apply: 71 72* If ``home`` is an absolute path and :envvar:`PYTHONHOME` is not set, this 73 path is used instead of the path to the main executable when deducing ``prefix`` 74 and ``exec_prefix``. 75 76_pth files 77---------- 78 79To completely override :data:`sys.path` create a ``._pth`` file with the same 80name as the shared library or executable (``python._pth`` or ``python311._pth``). 81The shared library path is always known on Windows, however it may not be 82available on other platforms. In the ``._pth`` file specify one line for each path 83to add to :data:`sys.path`. The file based on the shared library name overrides 84the one based on the executable, which allows paths to be restricted for any 85program loading the runtime if desired. 86 87When the file exists, all registry and environment variables are ignored, 88isolated mode is enabled, and :mod:`site` is not imported unless one line in the 89file specifies ``import site``. Blank paths and lines starting with ``#`` are 90ignored. Each path may be absolute or relative to the location of the file. 91Import statements other than to ``site`` are not permitted, and arbitrary code 92cannot be specified. 93 94Note that ``.pth`` files (without leading underscore) will be processed normally 95by the :mod:`site` module when ``import site`` has been specified. 96 97Embedded Python 98--------------- 99 100If Python is embedded within another application :c:func:`Py_InitializeFromConfig` and 101the :c:type:`PyConfig` structure can be used to initialize Python. The path specific 102details are described at :ref:`init-path-config`. Alternatively the older :c:func:`Py_SetPath` 103can be used to bypass the initialization of the module search path. 104 105.. seealso:: 106 107 * :ref:`windows_finding_modules` for detailed Windows notes. 108 * :ref:`using-on-unix` for Unix details. 109