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