diff --git a/source/specifications/virtual-environments.rst b/source/specifications/virtual-environments.rst index c73a28c27..7b2da9f04 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,40 @@ 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``. +* ``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. -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``. +- Nov 2026: Added ``python-version`` from :pep:`838`.