From 53e37b7c887a393190654a01fc80ee64da46bd7d Mon Sep 17 00:00:00 2001 From: konstin Date: Sat, 21 Nov 2026 12:13:05 +0100 Subject: [PATCH 1/2] Modernize virtual environments page --- .../specifications/virtual-environments.rst | 57 +++++++++++-------- 1 file changed, 33 insertions(+), 24 deletions(-) diff --git a/source/specifications/virtual-environments.rst b/source/specifications/virtual-environments.rst index c73a28c274..1dcd1e6aaa 100644 --- a/source/specifications/virtual-environments.rst +++ b/source/specifications/virtual-environments.rst @@ -1,17 +1,20 @@ .. _virtual-environments: -=========================== -Python Virtual Environments -=========================== +==================== +Virtual Environments +==================== -For Python 3.3 and later versions, :pep:`405` introduced interpreter level support -for the concept of "Python Virtual Environments". Each virtual environment has -its own Python binary (allowing creation of environments with various Python -versions) and can have its own independent set of installed Python packages in -its site directories, but shares the standard library with the base installed -Python. While the concept of virtual environments existed prior to this update, -there was no previously standardised mechanism for declaring or discovering them. +A virtual environment isolates a Python interpreter and its packages. The +virtual environment has its own Python binary (allowing creation of +environments with various Python versions) and can have its own independent set +of installed Python packages in its site directories, but shares the standard +library with the base installed Python. + +A Python interpreter detects whether it is in a virtual environment by looking +for a ``pyvenv.cfg`` file one or two levels above its executable (without +resolving symlinks). The ``pyvenv.cfg`` needs to have at least a ``home`` key +to declare a virtual environment. Runtime detection of virtual environments @@ -19,8 +22,8 @@ Runtime detection of virtual environments At runtime, virtual environments can be identified by virtue of :py:data:`sys.prefix` (the filesystem location of the running interpreter) -having a different value from :py:data:`sys.base_prefix` (the default filesystem -location of the standard library directories). +having a different value from :py:data:`sys.base_prefix` (the default +filesystem location of the standard library directories). :ref:`venv-explanation` in the Python standard library documentation for the :py:mod:`venv` module covers this along with the concept of "activating" a @@ -29,28 +32,34 @@ step is optional and hence the changes it makes can't be reliably used to detect whether a Python program is running in a virtual environment or not). -Declaring installation environments as Python virtual environments -================================================================== +``pyvenv.cfg`` +============== + +The ``pyvenv.cfg`` has lines in the form ``key = value``. The following keys +are defined: -As described in :pep:`405`, a Python virtual environment in its simplest form -consists of nothing more than a copy or symlink of the Python binary accompanied -by a ``site-packages`` directory and a ``pyvenv.cfg`` file with a ``home`` key -that indicates where to find the Python standard library modules. +* ``home``: The directory containing the Python executable used to create this + virtual environment. +* ``include-system-site-packages``: When ``true``, the ``site`` module will + also add the system site directories to ``sys.path`` after the virtual + environment site directories. If ``false``, the system site directories are + not included. Defaults to ``true``. -While designed to meet the needs of the standard :py:mod:`venv` module, this -split installation and ``pyvenv.cfg`` file approach can be used by *any* -Python installation provider that desires Python-specific tools to be aware that -they are already operating in a virtual environment and no further environment -nesting is required or desired. + +Declaring installation environments as Python virtual environments +================================================================== Even in the absence of a ``pyvenv.cfg`` file, any approach (e.g. ``sitecustomize.py``, patching the installed Python runtime) that results in :py:data:`sys.prefix` and :py:data:`sys.base_prefix` having different values, while still providing a matching default package installation scheme in -:py:mod:`sysconfig`, will be detected and behave as a Python virtual environment. +:py:mod:`sysconfig`, will be detected and behave as a Python virtual +environment. History ======= - May 2012: This specification was approved through :pep:`405`. +- Nov 2026: Removed PEP 405 references and clarified that + ``include-system-site-packages`` defaults to ``true``. From 86ce0db90f5020bf0b894a815669c6e79b3e8746 Mon Sep 17 00:00:00 2001 From: konstin Date: Sat, 21 Nov 2026 12:22:23 +0100 Subject: [PATCH 2/2] PEP 838: Add `python-version` to `pyvenv.cfg` Stacked on top of https://github.com/pypa/packaging.python.org/pull/2201. --- source/specifications/virtual-environments.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/source/specifications/virtual-environments.rst b/source/specifications/virtual-environments.rst index 1dcd1e6aaa..7b2da9f042 100644 --- a/source/specifications/virtual-environments.rst +++ b/source/specifications/virtual-environments.rst @@ -44,6 +44,11 @@ are defined: also add the system site directories to ``sys.path`` after the virtual environment site directories. If ``false``, the system site directories are not included. Defaults to ``true``. +* ``python-version``: Contains a string value with the major and minor version + of the Python interpreter, such as ``3.16``. The value can be obtained with + ``f"{sys.version_info[0]}.{sys.version_info[1]}"``. It omits the patch + version or any other version components. Tools MUST write ``python-version`` + to ``pyvenv.cfg`` when creating the virtual environment. Declaring installation environments as Python virtual environments @@ -63,3 +68,4 @@ History - May 2012: This specification was approved through :pep:`405`. - Nov 2026: Removed PEP 405 references and clarified that ``include-system-site-packages`` defaults to ``true``. +- Nov 2026: Added ``python-version`` from :pep:`838`.