Skip to content

DOC: clarify and expand documentation about PYTHONUSERBASE and PYTHONNOUSERSITE #144637

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tacaswell wants to merge 6 commits into
base: main
Choose a base branch
from
Open

DOC: clarify and expand documentation about PYTHONUSERBASE and PYTHONNOUSERSITE #144637

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
75f9dac
DOC: add cross reference to -s option to PYTHONNOUSERSITE env
tacaswell Feb 9, 2026
b4773b3
DOC: add note to PYTHONUSERBASE about PYHTONNOUSERSITE
tacaswell Feb 9, 2026
15ff842
DOC: fix details the value of include-system-site-packages
tacaswell Feb 9, 2026
6d4aa9a
DOC: document include-system-site-packages interaction with usersite
tacaswell Feb 9, 2026
1f7db82
DOC: soften language in note
tacaswell Feb 9, 2026
9cde670
DOC: add details of use site-packages to sys_path_init docs
tacaswell Feb 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion Doc/library/site.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
25 changes: 14 additions & 11 deletions Doc/library/sys_path_init.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Comment on lines +61 to +64
Copy link
Member

@FFY00 FFY00 Feb 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this should be in the paragraph below, together with their respective CLI flags.

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

Expand Down Expand Up @@ -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 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.
Comment on lines -99 to +106
Copy link
Member

@FFY00 FFY00 Feb 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I honestly don't think this paragraph needs a change. In fact, I think the new version removes some information that I think is helpful to the user.


_pth files
----------
Expand Down
8 changes: 6 additions & 2 deletions Doc/using/cmdline.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -941,8 +941,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::

Expand All @@ -956,6 +957,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
Expand Down
6 changes: 4 additions & 2 deletions Lib/site.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading