Get Python version from pyproject.toml

[knyghty]

For quite some time we've been able to use pyproject.toml to specify the Python version. and this is widely supported by tooling as well as being part of PEP 621, which is a bit better than using an ad-hoc standard such as a .python_version file.

It would be nice if we could use this in Heroku.

[edmorley]

@knyghty Hi! Thank you for opening an issue :-)

I'd love for there to be a standardised (ie specified in a PEP) way to determine the chosen Python version to install, however, unfortunately the python-requires field in pyproject.toml isn't semantically the same as what's in a .python-version file, since it's a range of versions compatible with the project (typically a library), rather than an exact version (or major version) to be installed locally. (The PEP440 syntax used by requires-python also has quite a few rough edges, for example that described in: astral-sh/uv#7426)

This is why our buildpacks (and tools like pyenv, uv etc) still use .python-version instead of requires-python.

There's some more background on this in:

• Support flexible patch version syntax to allow for automatic Python updates #913 (comment)
• Best practices for requires-python  astral-sh/uv#7429 (comment)
• Docs: Mention that .python-version is obsolete if project.requires-python is present in pyproject.toml? astral-sh/uv#8247

I'd personally love to see a new pyproject.toml field covered by a PEP that we could use for this purpose - if you were feeling adventurous, perhaps upstream would be receptive to a new PEP for it?

[knyghty]

Thanks for the reply and the thinking put into this.

I am aware of the version specifier oddness and I've been bitten by them myself in the past 😬. However I don't think a new PEP for this would land because adding a specific version is not what anyone wants (or should want - everyone wants security updates, right?). So either:

• you would still end up using the same version specifiers (I don't think they are open to being changed as they'd cause too many backwards incompatibility nightmares); or
• You have this new syntax similar to .python-version, which is arguably also confusing and not used anywhere else in Python

In the end I think python-requires is still the right way to go here. Yes there's some chance of footguns but they are at least known footguns. I believe the buildpack should simply choose the most recent version covered by the specifier that Heroku supports.

I accept there are no easy answers, and that even if python-requires is supported, .python-version would still be preferred if both exist. I'm also fine with just adding the damn file :)