ReleaseBytes
python Python PEPs ·

PEP 838 adds python-version to pyvenv.cfg

infra
announcement

PEP 838 proposes adding a standardized `python-version` field to `pyvenv.cfg` to record the major and minor version of the Python interpreter used by a virtual environment. This change aims to resolve inconsistencies across various tools that currently interpret version information differently, preventing potential failures after Python patch updates. The new field is designed for use by packaging tools and Python environments, with implementations planned for popular tools like uv, virtualenv, and CPython.

  • →Standardize virtual environment Python version tracking
  • →Improve resilience to Python patch version updates
  • →Provide reference implementations for packaging tools
  • →Address existing tool behavior and version inconsistencies
Features (1) ›
  • Standardize virtual environment Python version tracking

    PEP 838 introduces a `python-version` field to `pyvenv.cfg`, specifying only the major and minor version of the Python interpreter. This aims to create a consistent and resilient way for tools to identify the Python version associated with a virtual environment.

Enhancements (1) ›
  • Improve resilience to Python patch version updates

    By storing only the major and minor Python version, the `python-version` field in `pyvenv.cfg` remains accurate even when the underlying Python interpreter is updated with patch versions. This prevents tools from failing due to outdated version assumptions.

Maintenance (1) ›
  • Provide reference implementations for packaging tools

    Reference implementations for the `python-version` field are planned for popular Python packaging tools, including uv, virtualenv, and CPython. Documentation will also be added to the Python Packaging User Guide.

Notes (1) ›
  • Address existing tool behavior and version inconsistencies

    The PEP documents various existing methods tools use to determine Python versions from `pyvenv.cfg`, highlighting inconsistencies and potential issues. The new `python-version` field is designed to be a standardized replacement.

Read the original announcement →

https://peps.python.org/pep-0838/

Related releases