PEP 838: Adding python-version to pyvenv.cfg (as packaging topic)

I’d like to propose adding a python-version field to pyvenv.cfg. Unlike version and version_info, it records only the major and minor version and is resilient to patch version updates.

This is a small change: The implementation in virtualenv is for example an 8 line change (pypa/virtualenv#3193), in uv it’s a 36 line change of which 4 are production code (astral-sh/uv#20569).

This is a restart of this topic. Thanks to the Packaging Council, we now have a Standing Delegation where venv-related PEPs are decided by the PPC, and we can discuss this as a packaging topic instead of as a CPython change.

1 Like

Thanks @konstin for sharing this PEP. I reviewed the previous thread, and there’s a couple of outstanding items from that:

  1. (most important comment) Steve suggested standardizing version may be an alternative to adding python-version. It would be good to address that. This is the one design choice that seems open, so probably deserves a Rejected Alternative (or change the design to that).
  2. Specify the semantics of the recorded version more clearly, as Paul asked:
    • I think it’s the value at the time of creating the venv,
    • It needs a recommended or required behavior for tools if they detect that the minor version got bumped; or declare it as UB explicitly,
    • State what (if any) conclusions can be drawn from the version metadata matching the current interpreter.

The ABI and build-details.json suggestions in that thread don’t seem particularly relevant to me; they could get a brief mention in Rejected Alternatives perhaps.

It would be useful to add, probably in How to Teach This, a short explanation about how existing consumers are expected to migrate to python-version.

The implementation complexity is quite low and you linked multiple real-world issues in the motivation, so that seems :+1: to me. It would be useful to get a few thumbs up from maintainers of other tools that create venv’s - virtualenv, Hatch, Poetry, PDM come to mind - if possible[1].


  1. Placing more weight on opinions of the relevant tool authors is one of the main things the new Packaging Council wants to focus on, as documented in python/packaging-council:Packaging PEPs ↩︎