Doc/library/site.rst
!site --- Site-specific configuration hook.. module:: site :synopsis: Module responsible for site-specific configuration.
Source code: :source:Lib/site.py
.. highlight:: none
This module is automatically imported during initialization. The automatic
import can be suppressed using the interpreter's :option:-S option.
.. index:: triple: module; search; path
Importing this module normally appends site-specific paths to the module search path
and adds :ref:callables <site-consts>, including :func:help to the built-in
namespace. However, Python startup option :option:-S blocks this and this module
can be safely imported with no automatic modifications to the module search path
or additions to the builtins. To explicitly trigger the usual site-specific
additions, call the :func:main function.
.. versionchanged:: 3.3
Importing the module used to trigger paths manipulation even when using
:option:-S.
.. index:: pair: site-packages; directory
It starts by constructing up to four directories from a head and a tail part.
For the head part, it uses sys.prefix and sys.exec_prefix; empty heads
are skipped. For the tail part, it uses the empty string and then
:file:lib/site-packages (on Windows) or
:file:lib/python{X.Y[t]}/site-packages (on Unix and macOS). (The
optional suffix "t" indicates the :term:free-threaded build, and is
appended if "t" is present in the :data:sys.abiflags constant.)
For each
of the distinct head-tail combinations, it sees if it refers to an existing
directory, and if so, adds it to sys.path and also inspects the newly
added path for configuration files.
.. versionchanged:: 3.5 Support for the "site-python" directory has been removed.
.. versionchanged:: 3.13
On Unix, :term:Free threading <free threading> Python installations are
identified by the "t" suffix in the version-specific directory name, such as
:file:lib/python3.13t/.
.. versionchanged:: 3.14
:mod:!site is no longer responsible for updating :data:sys.prefix and
:data:sys.exec_prefix on :ref:sys-path-init-virtual-environments. This is
now done during the :ref:path initialization <sys-path-init>. As a result,
under :ref:sys-path-init-virtual-environments, :data:sys.prefix and
:data:sys.exec_prefix no longer depend on the :mod:!site initialization,
and are therefore unaffected by :option:-S.
.. _site-virtual-environments-configuration:
When running under a :ref:virtual environment <sys-path-init-virtual-environments>,
the pyvenv.cfg file in :data:sys.prefix is checked for site-specific
configurations. If the include-system-site-packages key exists and is set to
true (case-insensitive), the system-level prefixes will be searched for
site-packages, otherwise they won't. If the system-level prefixes are not searched then
the user site prefixes are also implicitly not searched for site-packages.
.. index:: single: # (hash); comment pair: statement; import
A path configuration file is a file whose name has the form :file:{name}.pth
and exists in one of the four directories mentioned above; its contents are
additional items (one per line) to be added to sys.path. Non-existing items
are never added to sys.path, and no check is made that the item refers to a
directory rather than a file. No item is added to sys.path more than
once. Blank lines and lines beginning with # are skipped. Lines starting
with import (followed by space or tab) are executed.
.. note::
An executable line in a :file:.pth file is run at every Python startup,
regardless of whether a particular module is actually going to be used.
Its impact should thus be kept to a minimum.
The primary intended purpose of executable lines is to make the
corresponding module(s) importable
(load 3rd-party import hooks, adjust :envvar:PATH etc).
Any other initialization is supposed to be done upon a module's
actual import, if and when it happens.
Limiting a code chunk to a single line is a deliberate measure
to discourage putting anything more complex here.
.. versionchanged:: 3.13
The :file:.pth files are now decoded by UTF-8 at first and then by the
:term:locale encoding if it fails.
.. index:: single: package triple: path; configuration; file
For example, suppose sys.prefix and sys.exec_prefix are set to
:file:/usr/local. The Python X.Y library is then installed in
:file:/usr/local/lib/python{X.Y}. Suppose this has
a subdirectory :file:/usr/local/lib/python{X.Y}/site-packages with three
subsubdirectories, :file:foo, :file:bar and :file:spam, and two path
configuration files, :file:foo.pth and :file:bar.pth. Assume
:file:foo.pth contains the following::
foo bar bletch
and :file:bar.pth contains::
bar
Then the following version-specific directories are added to
sys.path, in this order::
/usr/local/lib/pythonX.Y/site-packages/bar /usr/local/lib/pythonX.Y/site-packages/foo
Note that :file:bletch is omitted because it doesn't exist; the :file:bar
directory precedes the :file:foo directory because :file:bar.pth comes
alphabetically before :file:foo.pth; and :file:spam is omitted because it is
not mentioned in either path configuration file.
!sitecustomize.. module:: sitecustomize
After these path manipulations, an attempt is made to import a module named
:mod:!sitecustomize, which can perform arbitrary site-specific customizations.
It is typically created by a system administrator in the site-packages
directory. If this import fails with an :exc:ImportError or its subclass
exception, and the exception's :attr:~ImportError.name
attribute equals 'sitecustomize',
it is silently ignored. If Python is started without output streams available, as
with :file:pythonw.exe on Windows (which is used by default to start IDLE),
attempted output from :mod:!sitecustomize is ignored. Any other exception
causes a silent and perhaps mysterious failure of the process.
!usercustomize.. module:: usercustomize
After this, an attempt is made to import a module named :mod:!usercustomize,
which can perform arbitrary user-specific customizations, if
:data:~site.ENABLE_USER_SITE is true. This file is intended to be created in the
user site-packages directory (see below), which is part of sys.path unless
disabled by :option:-s. If this import fails with an :exc:ImportError or
its subclass exception, and the exception's :attr:~ImportError.name
attribute equals 'usercustomize', it is silently ignored.
Note that for some non-Unix systems, sys.prefix and sys.exec_prefix are
empty, and the path manipulations are skipped; however the import of
:mod:sitecustomize and :mod:!usercustomize is still attempted.
.. currentmodule:: site
.. _rlcompleter-config:
On systems that support :mod:readline, this module will also import and
configure the :mod:rlcompleter module, if Python is started in
:ref:interactive mode <tut-interactive> and without the :option:-S option.
The default behavior is to enable tab completion and to use
:file:~/.python_history as the history save file. To disable it, delete (or
override) the :data:sys.__interactivehook__ attribute in your
:mod:sitecustomize or :mod:usercustomize module or your
:envvar:PYTHONSTARTUP file.
.. versionchanged:: 3.4 Activation of rlcompleter and history was made automatic.
.. data:: PREFIXES
A list of prefixes for site-packages directories.
.. data:: ENABLE_USER_SITE
Flag showing the status of the user site-packages directory. True means
that it is enabled and was added to sys.path. False means that it
was disabled by user request (with :option:-s or
:envvar:PYTHONNOUSERSITE). None means it was disabled for security
reasons (mismatch between user or group id and effective id) or by an
administrator.
.. data:: USER_SITE
Path to the user site-packages for the running Python. Can be None if
:func:getusersitepackages hasn't been called yet. Default value is
:file:~/.local/lib/python{X.Y}[t]/site-packages for UNIX and non-framework
macOS builds, :file:~/Library/Python/{X.Y}/lib/python/site-packages for macOS
framework builds, and :file:{%APPDATA%}\\Python\\Python{XY}\\site-packages
on Windows. The optional "t" indicates the free-threaded build. This
directory is a site directory, which means that :file:.pth files in it
will be processed.
.. data:: USER_BASE
Path to the base directory for the user site-packages. Can be None if
:func:getuserbase hasn't been called yet. Default value is
:file:~/.local for UNIX and macOS non-framework builds,
:file:~/Library/Python/{X.Y} for macOS framework builds, and
:file:{%APPDATA%}\\Python for Windows. This value is used to
compute the installation directories for scripts, data files, Python modules,
etc. for the :ref:user installation scheme <sysconfig-user-scheme>.
See also :envvar:PYTHONUSERBASE.
.. function:: main()
Adds all the standard site-specific directories to the module search
path. This function is called automatically when this module is imported,
unless the Python interpreter was started with the :option:-S flag.
.. versionchanged:: 3.3 This function used to be called unconditionally.
.. function:: addsitedir(sitedir, known_paths=None)
Add a directory to sys.path and process its :file:.pth files. Typically
used in :mod:sitecustomize or :mod:usercustomize (see above).
.. function:: getsitepackages()
Return a list containing all global site-packages directories.
.. versionadded:: 3.2
.. function:: getuserbase()
Return the path of the user base directory, :data:USER_BASE. If it is not
initialized yet, this function will also set it, respecting
:envvar:PYTHONUSERBASE.
.. versionadded:: 3.2
.. function:: getusersitepackages()
Return the path of the user-specific site-packages directory,
:data:USER_SITE. If it is not initialized yet, this function will also set
it, respecting :data:USER_BASE. To determine if the user-specific
site-packages was added to sys.path :data:ENABLE_USER_SITE should be
used.
.. versionadded:: 3.2
.. _site-commandline:
.. program:: site
The :mod:!site module also provides a way to get the user directories from the
command line:
.. code-block:: shell-session
$ python -m site --user-site /home/user/.local/lib/python3.11/site-packages
If it is called without arguments, it will print the contents of
:data:sys.path on the standard output, followed by the value of
:data:USER_BASE and whether the directory exists, then the same thing for
:data:USER_SITE, and finally the value of :data:ENABLE_USER_SITE.
.. option:: --user-base
Print the path to the user base directory.
.. option:: --user-site
Print the path to the user site-packages directory.
If both options are given, user base and user site will be printed (always in
this order), separated by :data:os.pathsep.
If any option is given, the script will exit with one of these values: 0 if
the user site-packages directory is enabled, 1 if it was disabled by the
user, 2 if it is disabled for security reasons or by an administrator, and a
value greater than 2 if there is an error.
.. seealso::
370 -- Per user site-packages directorysys-path-init -- The initialization of :data:sys.path.