| 1 |
:mod:`!site` --- Site-specific configuration hook |
| 2 |
================================================= |
| 3 |
|
| 4 |
.. module:: site |
| 5 |
:synopsis: Module responsible for site-specific configuration. |
| 6 |
|
| 7 |
**Source code:** :source:`Lib/site.py` |
| 8 |
|
| 9 |
-------------- |
| 10 |
|
| 11 |
.. highlight:: none |
| 12 |
|
| 13 |
**This module is automatically imported during initialization.** The automatic |
| 14 |
import can be suppressed using the interpreter's :option:`-S` option. |
| 15 |
|
| 16 |
.. index:: triple: module; search; path |
| 17 |
|
| 18 |
Importing this module normally appends site-specific paths to the module search path |
| 19 |
and adds :ref:`callables <site-consts>`, including :func:`help` to the built-in |
| 20 |
namespace. However, Python startup option :option:`-S` blocks this and this module |
| 21 |
can be safely imported with no automatic modifications to the module search path |
| 22 |
or additions to the builtins. To explicitly trigger the usual site-specific |
| 23 |
additions, call the :func:`main` function. |
| 24 |
|
| 25 |
.. versionchanged:: 3.3 |
| 26 |
Importing the module used to trigger paths manipulation even when using |
| 27 |
:option:`-S`. |
| 28 |
|
| 29 |
.. index:: |
| 30 |
pair: site-packages; directory |
| 31 |
|
| 32 |
It starts by constructing up to four directories from a head and a tail part. |
| 33 |
For the head part, it uses ``sys.prefix`` and ``sys.exec_prefix``; empty heads |
| 34 |
are skipped. For the tail part, it uses the empty string and then |
| 35 |
:file:`lib/site-packages` (on Windows) or |
| 36 |
:file:`lib/python{X.Y[t]}/site-packages` (on Unix and macOS). (The |
| 37 |
optional suffix "t" indicates the :term:`free-threaded build`, and is |
| 38 |
appended if ``"t"`` is present in the :data:`sys.abiflags` constant.) |
| 39 |
For each |
| 40 |
of the distinct head-tail combinations, it sees if it refers to an existing |
| 41 |
directory, and if so, adds it to ``sys.path`` and also inspects the newly |
| 42 |
added path for configuration files. |
| 43 |
|
| 44 |
.. versionchanged:: 3.5 |
| 45 |
Support for the "site-python" directory has been removed. |
| 46 |
|
| 47 |
.. versionchanged:: 3.13 |
| 48 |
On Unix, :term:`Free threading <free threading>` Python installations are |
| 49 |
identified by the "t" suffix in the version-specific directory name, such as |
| 50 |
:file:`lib/python3.13t/`. |
| 51 |
|
| 52 |
.. versionchanged:: 3.14 |
| 53 |
|
| 54 |
:mod:`!site` is no longer responsible for updating :data:`sys.prefix` and |
| 55 |
:data:`sys.exec_prefix` on :ref:`sys-path-init-virtual-environments`. This is |
| 56 |
now done during the :ref:`path initialization <sys-path-init>`. As a result, |
| 57 |
under :ref:`sys-path-init-virtual-environments`, :data:`sys.prefix` and |
| 58 |
:data:`sys.exec_prefix` no longer depend on the :mod:`!site` initialization, |
| 59 |
and are therefore unaffected by :option:`-S`. |
| 60 |
|
| 61 |
.. _site-virtual-environments-configuration: |
| 62 |
|
| 63 |
When running under a :ref:`virtual environment <sys-path-init-virtual-environments>`, |
| 64 |
the ``pyvenv.cfg`` file in :data:`sys.prefix` is checked for site-specific |
| 65 |
configurations. If the ``include-system-site-packages`` key exists and is set to |
| 66 |
``true`` (case-insensitive), the system-level prefixes will be searched for |
| 67 |
site-packages, otherwise they won't. |
| 68 |
|
| 69 |
.. index:: |
| 70 |
single: # (hash); comment |
| 71 |
pair: statement; import |
| 72 |
|
| 73 |
A path configuration file is a file whose name has the form :file:`{name}.pth` |
| 74 |
and exists in one of the four directories mentioned above; its contents are |
| 75 |
additional items (one per line) to be added to ``sys.path``. Non-existing items |
| 76 |
are never added to ``sys.path``, and no check is made that the item refers to a |
| 77 |
directory rather than a file. No item is added to ``sys.path`` more than |
| 78 |
once. Blank lines and lines beginning with ``#`` are skipped. Lines starting |
| 79 |
with ``import`` (followed by space or tab) are executed. |
| 80 |
|
| 81 |
.. note:: |
| 82 |
|
| 83 |
An executable line in a :file:`.pth` file is run at every Python startup, |
| 84 |
regardless of whether a particular module is actually going to be used. |
| 85 |
Its impact should thus be kept to a minimum. |
| 86 |
The primary intended purpose of executable lines is to make the |
| 87 |
corresponding module(s) importable |
| 88 |
(load 3rd-party import hooks, adjust :envvar:`PATH` etc). |
| 89 |
Any other initialization is supposed to be done upon a module's |
| 90 |
actual import, if and when it happens. |
| 91 |
Limiting a code chunk to a single line is a deliberate measure |
| 92 |
to discourage putting anything more complex here. |
| 93 |
|
| 94 |
.. versionchanged:: 3.13 |
| 95 |
The :file:`.pth` files are now decoded by UTF-8 at first and then by the |
| 96 |
:term:`locale encoding` if it fails. |
| 97 |
|
| 98 |
.. index:: |
| 99 |
single: package |
| 100 |
triple: path; configuration; file |
| 101 |
|
| 102 |
For example, suppose ``sys.prefix`` and ``sys.exec_prefix`` are set to |
| 103 |
:file:`/usr/local`. The Python X.Y library is then installed in |
| 104 |
:file:`/usr/local/lib/python{X.Y}`. Suppose this has |
| 105 |
a subdirectory :file:`/usr/local/lib/python{X.Y}/site-packages` with three |
| 106 |
subsubdirectories, :file:`foo`, :file:`bar` and :file:`spam`, and two path |
| 107 |
configuration files, :file:`foo.pth` and :file:`bar.pth`. Assume |
| 108 |
:file:`foo.pth` contains the following:: |
| 109 |
|
| 110 |
# foo package configuration |
| 111 |
|
| 112 |
foo |
| 113 |
bar |
| 114 |
bletch |
| 115 |
|
| 116 |
and :file:`bar.pth` contains:: |
| 117 |
|
| 118 |
# bar package configuration |
| 119 |
|
| 120 |
bar |
| 121 |
|
| 122 |
Then the following version-specific directories are added to |
| 123 |
``sys.path``, in this order:: |
| 124 |
|
| 125 |
/usr/local/lib/pythonX.Y/site-packages/bar |
| 126 |
/usr/local/lib/pythonX.Y/site-packages/foo |
| 127 |
|
| 128 |
Note that :file:`bletch` is omitted because it doesn't exist; the :file:`bar` |
| 129 |
directory precedes the :file:`foo` directory because :file:`bar.pth` comes |
| 130 |
alphabetically before :file:`foo.pth`; and :file:`spam` is omitted because it is |
| 131 |
not mentioned in either path configuration file. |
| 132 |
|
| 133 |
:mod:`!sitecustomize` |
| 134 |
--------------------- |
| 135 |
|
| 136 |
.. module:: sitecustomize |
| 137 |
|
| 138 |
After these path manipulations, an attempt is made to import a module named |
| 139 |
:mod:`!sitecustomize`, which can perform arbitrary site-specific customizations. |
| 140 |
It is typically created by a system administrator in the site-packages |
| 141 |
directory. If this import fails with an :exc:`ImportError` or its subclass |
| 142 |
exception, and the exception's :attr:`~ImportError.name` |
| 143 |
attribute equals ``'sitecustomize'``, |
| 144 |
it is silently ignored. If Python is started without output streams available, as |
| 145 |
with :file:`pythonw.exe` on Windows (which is used by default to start IDLE), |
| 146 |
attempted output from :mod:`!sitecustomize` is ignored. Any other exception |
| 147 |
causes a silent and perhaps mysterious failure of the process. |
| 148 |
|
| 149 |
:mod:`!usercustomize` |
| 150 |
--------------------- |
| 151 |
|
| 152 |
.. module:: usercustomize |
| 153 |
|
| 154 |
After this, an attempt is made to import a module named :mod:`!usercustomize`, |
| 155 |
which can perform arbitrary user-specific customizations, if |
| 156 |
:data:`~site.ENABLE_USER_SITE` is true. This file is intended to be created in the |
| 157 |
user site-packages directory (see below), which is part of ``sys.path`` unless |
| 158 |
disabled by :option:`-s`. If this import fails with an :exc:`ImportError` or |
| 159 |
its subclass exception, and the exception's :attr:`~ImportError.name` |
| 160 |
attribute equals ``'usercustomize'``, it is silently ignored. |
| 161 |
|
| 162 |
Note that for some non-Unix systems, ``sys.prefix`` and ``sys.exec_prefix`` are |
| 163 |
empty, and the path manipulations are skipped; however the import of |
| 164 |
:mod:`sitecustomize` and :mod:`!usercustomize` is still attempted. |
| 165 |
|
| 166 |
.. currentmodule:: site |
| 167 |
|
| 168 |
.. _rlcompleter-config: |
| 169 |
|
| 170 |
Readline configuration |
| 171 |
---------------------- |
| 172 |
|
| 173 |
On systems that support :mod:`readline`, this module will also import and |
| 174 |
configure the :mod:`rlcompleter` module, if Python is started in |
| 175 |
:ref:`interactive mode <tut-interactive>` and without the :option:`-S` option. |
| 176 |
The default behavior is to enable tab completion and to use |
| 177 |
:file:`~/.python_history` as the history save file. To disable it, delete (or |
| 178 |
override) the :data:`sys.__interactivehook__` attribute in your |
| 179 |
:mod:`sitecustomize` or :mod:`usercustomize` module or your |
| 180 |
:envvar:`PYTHONSTARTUP` file. |
| 181 |
|
| 182 |
.. versionchanged:: 3.4 |
| 183 |
Activation of rlcompleter and history was made automatic. |
| 184 |
|
| 185 |
|
| 186 |
Module contents |
| 187 |
--------------- |
| 188 |
|
| 189 |
.. data:: PREFIXES |
| 190 |
|
| 191 |
A list of prefixes for site-packages directories. |
| 192 |
|
| 193 |
|
| 194 |
.. data:: ENABLE_USER_SITE |
| 195 |
|
| 196 |
Flag showing the status of the user site-packages directory. ``True`` means |
| 197 |
that it is enabled and was added to ``sys.path``. ``False`` means that it |
| 198 |
was disabled by user request (with :option:`-s` or |
| 199 |
:envvar:`PYTHONNOUSERSITE`). ``None`` means it was disabled for security |
| 200 |
reasons (mismatch between user or group id and effective id) or by an |
| 201 |
administrator. |
| 202 |
|
| 203 |
|
| 204 |
.. data:: USER_SITE |
| 205 |
|
| 206 |
Path to the user site-packages for the running Python. Can be ``None`` if |
| 207 |
:func:`getusersitepackages` hasn't been called yet. Default value is |
| 208 |
:file:`~/.local/lib/python{X.Y}[t]/site-packages` for UNIX and non-framework |
| 209 |
macOS builds, :file:`~/Library/Python/{X.Y}/lib/python/site-packages` for macOS |
| 210 |
framework builds, and :file:`{%APPDATA%}\\Python\\Python{XY}\\site-packages` |
| 211 |
on Windows. The optional "t" indicates the free-threaded build. This |
| 212 |
directory is a site directory, which means that :file:`.pth` files in it |
| 213 |
will be processed. |
| 214 |
|
| 215 |
|
| 216 |
.. data:: USER_BASE |
| 217 |
|
| 218 |
Path to the base directory for the user site-packages. Can be ``None`` if |
| 219 |
:func:`getuserbase` hasn't been called yet. Default value is |
| 220 |
:file:`~/.local` for UNIX and macOS non-framework builds, |
| 221 |
:file:`~/Library/Python/{X.Y}` for macOS framework builds, and |
| 222 |
:file:`{%APPDATA%}\\Python` for Windows. This value is used to |
| 223 |
compute the installation directories for scripts, data files, Python modules, |
| 224 |
etc. for the :ref:`user installation scheme <sysconfig-user-scheme>`. |
| 225 |
See also :envvar:`PYTHONUSERBASE`. |
| 226 |
|
| 227 |
|
| 228 |
.. function:: main() |
| 229 |
|
| 230 |
Adds all the standard site-specific directories to the module search |
| 231 |
path. This function is called automatically when this module is imported, |
| 232 |
unless the Python interpreter was started with the :option:`-S` flag. |
| 233 |
|
| 234 |
.. versionchanged:: 3.3 |
| 235 |
This function used to be called unconditionally. |
| 236 |
|
| 237 |
|
| 238 |
.. function:: addsitedir(sitedir, known_paths=None) |
| 239 |
|
| 240 |
Add a directory to sys.path and process its :file:`.pth` files. Typically |
| 241 |
used in :mod:`sitecustomize` or :mod:`usercustomize` (see above). |
| 242 |
|
| 243 |
|
| 244 |
.. function:: getsitepackages() |
| 245 |
|
| 246 |
Return a list containing all global site-packages directories. |
| 247 |
|
| 248 |
.. versionadded:: 3.2 |
| 249 |
|
| 250 |
|
| 251 |
.. function:: getuserbase() |
| 252 |
|
| 253 |
Return the path of the user base directory, :data:`USER_BASE`. If it is not |
| 254 |
initialized yet, this function will also set it, respecting |
| 255 |
:envvar:`PYTHONUSERBASE`. |
| 256 |
|
| 257 |
.. versionadded:: 3.2 |
| 258 |
|
| 259 |
|
| 260 |
.. function:: getusersitepackages() |
| 261 |
|
| 262 |
Return the path of the user-specific site-packages directory, |
| 263 |
:data:`USER_SITE`. If it is not initialized yet, this function will also set |
| 264 |
it, respecting :data:`USER_BASE`. To determine if the user-specific |
| 265 |
site-packages was added to ``sys.path`` :data:`ENABLE_USER_SITE` should be |
| 266 |
used. |
| 267 |
|
| 268 |
.. versionadded:: 3.2 |
| 269 |
|
| 270 |
|
| 271 |
.. _site-commandline: |
| 272 |
|
| 273 |
Command-line interface |
| 274 |
---------------------- |
| 275 |
|
| 276 |
.. program:: site |
| 277 |
|
| 278 |
The :mod:`!site` module also provides a way to get the user directories from the |
| 279 |
command line: |
| 280 |
|
| 281 |
.. code-block:: shell-session |
| 282 |
|
| 283 |
$ python -m site --user-site |
| 284 |
/home/user/.local/lib/python3.11/site-packages |
| 285 |
|
| 286 |
If it is called without arguments, it will print the contents of |
| 287 |
:data:`sys.path` on the standard output, followed by the value of |
| 288 |
:data:`USER_BASE` and whether the directory exists, then the same thing for |
| 289 |
:data:`USER_SITE`, and finally the value of :data:`ENABLE_USER_SITE`. |
| 290 |
|
| 291 |
.. option:: --user-base |
| 292 |
|
| 293 |
Print the path to the user base directory. |
| 294 |
|
| 295 |
.. option:: --user-site |
| 296 |
|
| 297 |
Print the path to the user site-packages directory. |
| 298 |
|
| 299 |
If both options are given, user base and user site will be printed (always in |
| 300 |
this order), separated by :data:`os.pathsep`. |
| 301 |
|
| 302 |
If any option is given, the script will exit with one of these values: ``0`` if |
| 303 |
the user site-packages directory is enabled, ``1`` if it was disabled by the |
| 304 |
user, ``2`` if it is disabled for security reasons or by an administrator, and a |
| 305 |
value greater than 2 if there is an error. |
| 306 |
|
| 307 |
.. seealso:: |
| 308 |
|
| 309 |
* :pep:`370` -- Per user site-packages directory |
| 310 |
* :ref:`sys-path-init` -- The initialization of :data:`sys.path`. |
| 311 |
|