Docs: Mention that `.python-version` is obsolete if `project.requires-python` is present in `pyproject.toml`?

[jnussbaum]

First a big thumbs up for the great work you're doing with ruff and uv! We have adopted both in our company, and we're overwhelmed!

I have just a quick request for clarification: https://docs.astral.sh/uv/guides/projects/ implies that it is always necessary (or at least best practice) to have the file .python-version checked in. But for standards-compliant projects that define project.requires-python in pyproject.toml, this seems obsolete. I tried it out, and in fact, uv correctly detects project.requires-python and installs the intended python version, even without .python-version.

In our project, I wanted to remove .python-version, so that we don't have the python version defined in 2 separate places. But then I became insecure because of the documentation.

Therefore, I think it would be helpful to add a remark to https://docs.astral.sh/uv/guides/projects/, mentioning that .python-version is obsolete in this case. WDYT?

[charliermarsh]

The .python-version file is not quite obsolete with requires-python -- they're subtly different. requires-python is the range of versions supported by your project. .python-version is the exact version you want to use when developing. For example, if you're working on a library, your requires-python might be >= "3.10". But when developing on your machine, you might want to use 3.12.4 by default -- so you'd set that in a .python-version.

[jnussbaum]

Thanks for this information, that makes sense 👍

[apoorvkh]

Hey, I wonder if we can just add a tool.uv.python-resolution (which could be highest, lowest, lowest-major, 3.10.15, etc.) but would be overriden if .python-version does exist.

This would save projects from one excess file (.python-version) in the git tracking. And would permit maintainers to specify a certain Python version for development, but give contributors a hook to change this if desired (and without altering any git-tracked file).

Happy to attempt a PR if this sounds reasonable!

[zanieb]

See #5609 and https://github.com/astral-sh/uv/issues/7779

Yeah; I'd like to have a python-strategy or something, it just hasn't been implemented. If you're interested, you're welcome to give it a go.

[ANL06488]

I understand the need for specifically specifying a python version, but I would argue a better default behaviour for uv init should be to specify this as a separate setting within pyproject.toml with the same reasoning as in #8920 , AKA, not worth adding a whole new file to the root folder for.

[charliermarsh]

They have different meanings though. requires-python is not meant for that purpose -- it's meant to indicate your minimum-supported Python version. They're distinct concepts, and I don't think it's a good practice to encourage them to be mixed like that.

[ANL06488]

They have different meanings though. requires-python is not meant for that purpose -- it's meant to indicate your minimum-supported Python version. They're distinct concepts, and I don't think it's a good practice to encourage them to be mixed like that.

No, I'm saying add a specific tools.uv setting like python-version inside pyproject.toml apart from the existing requires-python setting.

Yes there's a need to specify a specific python version, but there's no need for it to be specified in a separate file, much less dedicate an entire file for a single config setting.

[apoorvkh]

[I said I would try a PR for this above, but I have little Rust experience, so this is subject to my schedule. Anyone else should feel free to work on this too! Would be really great to have this feature.]

[zanieb]

There are already issues tracking that at https://github.com/astral-sh/uv/issues/4970 and https://github.com/astral-sh/uv/issues/4359

There is a reason to have it in a separate file — other tools can read it. For example, GitHub Actions's setup-python action can read a version from a .python-file but not from a [tool.uv] option.

[ANL06488]

I see, once those PRs are merged, I'd still argue that the default behaviour should still be to put it in pyproject.toml first, and if needed a user can always move it to it's own file.