Debian Codegraph @

Doc/library/sys_path_init.rst

raw
1 .. _sys-path-init:
2
3 The initialization of the :data:`sys.path` module search path
4 =============================================================
5
6 A module search path is initialized when Python starts. This module search path
7 may be accessed at :data:`sys.path`.
8
9 The first entry in the module search path is the directory that contains the
10 input script, if there is one. Otherwise, the first entry is the current
11 directory, which is the case when executing the interactive shell, a :option:`-c`
12 command, or :option:`-m` module.
13
14 The :envvar:`PYTHONPATH` environment variable is often used to add directories
15 to the search path. If this environment variable is found then the contents are
16 added 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
24 The next items added are the directories containing standard Python modules as
25 well as any :term:`extension module`\s that these modules depend on. Extension
26 modules are ``.pyd`` files on Windows and ``.so`` files on other platforms. The
27 directory with the platform-independent Python modules is called ``prefix``.
28 The directory with the extension modules is called ``exec_prefix``.
29
30 The :envvar:`PYTHONHOME` environment variable may be used to set the ``prefix``
31 and ``exec_prefix`` locations. Otherwise these directories are found by using
32 the Python executable as a starting point and then looking for various 'landmark'
33 files and directories. Note that any symbolic links are followed so the real
34 Python executable location is used as the search starting point. The Python
35 executable location is called ``home``.
36
37 Once ``home`` is determined, the ``prefix`` directory is found by first looking
38 for :file:`python{majorversion}{minorversion}.zip` (``python311.zip``). On Windows
39 the zip archive is searched for in ``home`` and on Unix the archive is expected
40 to be in :file:`lib`. Note that the expected zip archive location is added to the
41 module search path even if the archive does not exist. If no archive was found,
42 Python on Windows will continue the search for ``prefix`` by looking for :file:`Lib\\os.py`.
43 Python 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,
45 however 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,
48 see :data:`sys.platlibdir` and :envvar:`PYTHONPLATLIBDIR`.
49
50 Once found, ``prefix`` and ``exec_prefix`` are available at
51 :data:`sys.base_prefix` and :data:`sys.base_exec_prefix` respectively.
52
53 If :envvar:`PYTHONHOME` is not set, and a ``pyvenv.cfg`` file is found alongside
54 the main executable, or in its parent directory, :data:`sys.prefix` and
55 :data:`sys.exec_prefix` get set to the directory containing ``pyvenv.cfg``,
56 otherwise they are set to the same value as :data:`sys.base_prefix` and
57 :data:`sys.base_exec_prefix`, respectively.
58 This is used by :ref:`sys-path-init-virtual-environments`.
59
60 Finally, the :mod:`site` module is processed and :file:`site-packages` directories
61 are added to the module search path. A common way to customize the search path is
62 to create :mod:`sitecustomize` or :mod:`usercustomize` modules as described in
63 the :mod:`site` module documentation.
64
65 .. note::
66
67 Certain command line options may further affect path calculations.
68 See :option:`-E`, :option:`-I`, :option:`-s` and :option:`-S` for further details.
69
70 .. versionchanged:: 3.14
71
72 :data:`sys.prefix` and :data:`sys.exec_prefix` are now set to the
73 ``pyvenv.cfg`` directory during the path initialization. This was previously
74 done by :mod:`site`, therefore affected by :option:`-S`.
75
76 .. _sys-path-init-virtual-environments:
77
78 Virtual Environments
79 --------------------
80
81 Virtual environments place a ``pyvenv.cfg`` file in their prefix, which causes
82 :data:`sys.prefix` and :data:`sys.exec_prefix` to point to them, instead of the
83 base installation.
84
85 The ``prefix`` and ``exec_prefix`` values of the base installation are available
86 at :data:`sys.base_prefix` and :data:`sys.base_exec_prefix`.
87
88 As well as being used as a marker to identify virtual environments,
89 ``pyvenv.cfg`` may also be used to configure the :mod:`site` initialization.
90 Please refer to :mod:`site`'s
91 :ref:`virtual environments documentation <site-virtual-environments-configuration>`.
92
93 .. note::
94
95 :envvar:`PYTHONHOME` overrides the ``pyvenv.cfg`` detection.
96
97 .. note::
98
99 There are other ways how "virtual environments" could be implemented, this
100 documentation refers implementations based on the ``pyvenv.cfg`` mechanism,
101 such as :mod:`venv`. Most virtual environment implementations follow the
102 model set by :mod:`venv`, but there may be exotic implementations that
103 diverge from it.
104
105 _pth files
106 ----------
107
108 To completely override :data:`sys.path` create a ``._pth`` file with the same
109 name as the shared library or executable (``python._pth`` or ``python311._pth``).
110 The shared library path is always known on Windows, however it may not be
111 available on other platforms. In the ``._pth`` file specify one line for each path
112 to add to :data:`sys.path`. The file based on the shared library name overrides
113 the one based on the executable, which allows paths to be restricted for any
114 program loading the runtime if desired.
115
116 When the file exists, all registry and environment variables are ignored,
117 isolated mode is enabled, and :mod:`site` is not imported unless one line in the
118 file specifies ``import site``. Blank paths and lines starting with ``#`` are
119 ignored. Each path may be absolute or relative to the location of the file.
120 Import statements other than to ``site`` are not permitted, and arbitrary code
121 cannot be specified.
122
123 Note that ``.pth`` files (without leading underscore) will be processed normally
124 by the :mod:`site` module when ``import site`` has been specified.
125
126 Embedded Python
127 ---------------
128
129 If Python is embedded within another application :c:func:`Py_InitializeFromConfig` and
130 the :c:type:`PyConfig` structure can be used to initialize Python. The path specific
131 details are described at :ref:`init-path-config`.
132
133 .. seealso::
134
135 * :ref:`windows_finding_modules` for detailed Windows notes.
136 * :ref:`using-on-unix` for Unix details.