From 75f9dac5f74da72473b1e48b7c4ce4a2fd72ca2f Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Mon, 9 Feb 2026 13:25:32 -0500 Subject: [PATCH 1/6] DOC: add cross reference to -s option to PYTHONNOUSERSITE env --- Doc/using/cmdline.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index c97058119ae838..92731413f267e1 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -941,8 +941,9 @@ conflict. .. envvar:: PYTHONNOUSERSITE - If this is set, Python won't add the :data:`user site-packages directory - ` 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 ` to + :data:`sys.path`. .. seealso:: From b4773b3bb425d6cf1d5d0b797542b7277b5ccd84 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Mon, 9 Feb 2026 13:26:29 -0500 Subject: [PATCH 2/6] DOC: add note to PYTHONUSERBASE about PYHTONNOUSERSITE Otherwise it is not clear how to disable user site-packages. Even though it is directly above, the link from the search results put the top of the page on PYHONUSERBASE and the user may not think to scroll up for critical context. --- Doc/using/cmdline.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index 92731413f267e1..832bf785a2e4a5 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -957,6 +957,9 @@ conflict. and :ref:`installation paths ` 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 From 15ff842798353f1bb917c196ba9ab7c7264abd38 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Mon, 9 Feb 2026 13:28:24 -0500 Subject: [PATCH 3/6] DOC: fix details the value of include-system-site-packages Now matches both site.rst and the actual implementation. --- Lib/site.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Lib/site.py b/Lib/site.py index 1b7a656551b853..bfc1434b01eca5 100644 --- a/Lib/site.py +++ b/Lib/site.py @@ -18,7 +18,7 @@ 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. From 6d4aa9a01beec1820b79ed1af647dc7ec7e0d4e1 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Mon, 9 Feb 2026 13:29:49 -0500 Subject: [PATCH 4/6] DOC: document include-system-site-packages interaction with usersite It is not otherwise documented that this implicitly disables user site-packages. --- Doc/library/site.rst | 3 ++- Lib/site.py | 4 +++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/Doc/library/site.rst b/Doc/library/site.rst index 09a98b4e3b22af..08f8b1859e6ba2 100644 --- a/Doc/library/site.rst +++ b/Doc/library/site.rst @@ -64,7 +64,8 @@ When running under a :ref:`virtual environment Date: Mon, 9 Feb 2026 13:31:03 -0500 Subject: [PATCH 5/6] DOC: soften language in note --- Doc/library/sys_path_init.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/Doc/library/sys_path_init.rst b/Doc/library/sys_path_init.rst index a37bb59e7cec76..476b52ea1ab796 100644 --- a/Doc/library/sys_path_init.rst +++ b/Doc/library/sys_path_init.rst @@ -96,11 +96,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 many ways how "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 ---------- From 9cde67088ca9961b3b0a9985956b8d67b27ba0ce Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Mon, 9 Feb 2026 15:18:29 -0500 Subject: [PATCH 6/6] DOC: add details of use site-packages to sys_path_init docs --- Doc/library/sys_path_init.rst | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/Doc/library/sys_path_init.rst b/Doc/library/sys_path_init.rst index 476b52ea1ab796..5399b7cd22ea35 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