https://github.com/python/cpython/commit/201d251567738c234081329a244449e08fa86245
commit: 201d251567738c234081329a244449e08fa86245
branch: main
author: Thomas A Caswell <[email protected]>
committer: FFY00 <[email protected]>
date: 2026-03-02T15:54:26Z
summary:
DOC: clarify and expand documentation about PYTHONUSERBASE and PYTHONNOUSERSITE
(#144637)
files:
M Doc/library/site.rst
M Doc/library/sys_path_init.rst
M Doc/using/cmdline.rst
M Lib/site.py
diff --git a/Doc/library/site.rst b/Doc/library/site.rst
index 4686c9fc92ced2..04895ae4ec524b 100644
--- a/Doc/library/site.rst
+++ b/Doc/library/site.rst
@@ -64,7 +64,8 @@ When running under a :ref:`virtual environment
<sys-path-init-virtual-environmen
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.
+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
diff --git a/Doc/library/sys_path_init.rst b/Doc/library/sys_path_init.rst
index a37bb59e7cec76..e6c2cddbe84248 100644
--- a/Doc/library/sys_path_init.rst
+++ b/Doc/library/sys_path_init.rst
@@ -57,15 +57,19 @@ otherwise they are set to the same value as
:data:`sys.base_prefix` and
:data:`sys.base_exec_prefix`, respectively.
This is used by :ref:`sys-path-init-virtual-environments`.
-Finally, the :mod:`site` module is processed and :file:`site-packages`
directories
-are added to the module search path. A common way to customize the search path
is
-to create :mod:`sitecustomize` or :mod:`usercustomize` modules as described in
-the :mod:`site` module documentation.
+Finally, the :mod:`site` module is processed and :file:`site-packages`
+directories are added to the module search path. The :envvar:`PYTHONUSERBASE`
+environment variable controls where is searched for user site-packages and the
+:envvar:`PYTHONNOUSERSITE` environment variable prevents searching for user
+site-packages all together. A common way to customize the search path is to
+create :mod:`sitecustomize` or :mod:`usercustomize` modules as described in the
+:mod:`site` module documentation.
.. note::
- Certain command line options may further affect path calculations.
- See :option:`-E`, :option:`-I`, :option:`-s` and :option:`-S` for further
details.
+ The command line options :option:`-E`, :option:`-P`, :option:`-I`,
+ :option:`-S` and :option:`-s` further affect path calculations, see their
+ documentation for details.
.. versionchanged:: 3.14
@@ -96,11 +100,10 @@ Please refer to :mod:`site`'s
.. note::
- There are other ways how "virtual environments" could be implemented, this
- documentation refers implementations based on the ``pyvenv.cfg`` mechanism,
- such as :mod:`venv`. Most virtual environment implementations follow the
- model set by :mod:`venv`, but there may be exotic implementations that
- diverge from it.
+ There are other ways "virtual environments" could be implemented.
+ This documentation refers to implementations based on the ``pyvenv.cfg``
+ mechanism, such as :mod:`venv`, that many virtual environment
implementations
+ follow.
_pth files
----------
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index 93df4fcdc630a5..f4085ff842aea9 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -949,8 +949,9 @@ conflict.
.. envvar:: PYTHONNOUSERSITE
- If this is set, Python won't add the :data:`user site-packages directory
- <site.USER_SITE>` to :data:`sys.path`.
+ This is equivalent to the :option:`-s` option. If this is set, Python won't
+ add the :data:`user site-packages directory <site.USER_SITE>` to
+ :data:`sys.path`.
.. seealso::
@@ -964,6 +965,9 @@ conflict.
and :ref:`installation paths <sysconfig-user-scheme>` for
``python -m pip install --user``.
+ To disable the user site-packages, see :envvar:`PYTHONNOUSERSITE` or the
:option:`-s`
+ option.
+
.. seealso::
:pep:`370` -- Per user site-packages directory
diff --git a/Lib/site.py b/Lib/site.py
index 1b7a656551b853..5f09a7dd8c91c0 100644
--- a/Lib/site.py
+++ b/Lib/site.py
@@ -18,9 +18,11 @@
it is also checked for site-packages (sys.base_prefix and
sys.base_exec_prefix will always be the "real" prefixes of the Python
installation). If "pyvenv.cfg" (a bootstrap configuration file) contains
-the key "include-system-site-packages" set to anything other than "false"
+the key "include-system-site-packages" is set to "true"
(case-insensitive), the system-level prefixes will still also be
-searched for site-packages; otherwise they won't.
+searched for site-packages; otherwise they won't. If the system-level
+prefixes are not included then the user site prefixes are also implicitly
+not searched for site-packages.
All of the resulting site-specific directories, if they exist, are
appended to sys.path, and also inspected for path configuration
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
