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

Merged
FFY00 merged 8 commits into from
Mar 2, 2026
+26 −16
Merged

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

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
8 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
0f84e9b
DOC: tweak wording in note on alternative virtualenv implementations
tacaswell Feb 26, 2026
d532b81
Apply suggestion from @FFY00
FFY00 Mar 2, 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 thread
FFY00 marked this conversation as resolved.
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
Copy Markdown
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.

Copy link
Copy Markdown
Contributor Author

@tacaswell tacaswell Feb 24, 2026

Choose a reason for hiding this comment

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

I do not think this edit removes any factual information, but agree it could be word smithed a bit.

Copy link
Copy Markdown
Member

@FFY00 FFY00 Feb 25, 2026

Choose a reason for hiding this comment

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

The old text points out that most virtual environment implementations use pyvenv.cfg, and reminds the user that there are still other implementations. The new text removes emphasis on pyvenv.cfg being the main mechanism used in most virtual environment implementations. That's what I meant, sorry!

Copy link
Copy Markdown
Contributor Author

@tacaswell tacaswell Feb 26, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

"virtual environments" is a bit of a slippery term as it can both mean the very specific family of implementations that rely on pyvenv.cfg and a generic "isolated user space Python". Neither pixi nor conda currently drop this file in their environments (how I got started down this path was an issue at work on a shared system where some had done pip install --user and it was then leaking into and breaking pixi environments).

I consider those mainstream tools for the looser meaning the term and in that context the previous text was at best misleading.

I tweaked the first sentence a bit.


_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