Skip to content
Open
Changes from all commits
Commits
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
63 changes: 39 additions & 24 deletions source/specifications/virtual-environments.rst
Original file line number Diff line number Diff line change
@@ -1,26 +1,29 @@

.. _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
=========================================

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
Expand All @@ -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`.
Loading