Does `uv python pin 3.xx` also update pyproject.toml and uv.lock?

[adityashukzy]

Question

Hello, I'm relatively new to uv.

I cloned a git repo of mine to begin with, and then uv init'ed within the folder. This initialized the usual files (pyproject.toml, main.py, uv.lock, etc.).

However, at this point, the Python version picked up in .python-version was the default one in my usr/bin/python which was Python 3.9.

I wanted instead for it to install and use Python 3.10 for this project.

Thus, I ran the following:

1. uv python install 3.10
2. uv python pin 3.10

Now, as expected this change is reflected in the .python-version file (which displays 3.10). However, the pyproject.toml and uv.loc files still show the old info.

pyproject.toml:

requires-python = ">=3.9"

uv.lock:

version = 1
revision = 2
requires-python = ">=3.9"

Questions:

1. Do I manually need to change the values for requires-python in the above 2 files after doing uv python pin 3.xx? Is that even required? If so, why is that not taken care of by the pin command?
2. As I understand it, uv python install 3.10 will install that Python version globally? Is there any way to install python only for this project / associated environment? I do not wish to pollute the global space with multiple Python versions.

As I am new, I may have some incorrect assumptions. So please correct me where needed.

uv has been a fantastic tool so far, so kudos to the community!

Thank you!

Platform

macOS Sequoia 15.5 (Darwin 24.5.0 arm64)

Version

uv 0.8.2 (21fadbc 2025-07-22)

[zanieb]

1. Yeah. The pin command is intended to change your default version. Since it's compatible with your requires-python range, there's nothing that needs to change in the pyproject.toml. The uv.lock includes all possible Python versions already and doesn't need to change.
2. What is the concern about polluting the global namespace? i.e., where do you not want that Python to be available?

[adityashukzy]

Okay that makes sense!

As to the latter question, I would imagine that multiple Python installations across the global namespace could lead to package / dependency conflicts, and this is the reason behind the typical advice to contain Python libraries (incl. the Python version itself) inside neat environments.

Am I mistaken in this understanding?

PS: my apologies for the late response - Github did not notify me for some reason. Thank you!

[gwangjinkim]

I think - from the user's perspective - uv python pin x.x.x should say something whenever there are contradictions with the current Python version in tye pyproject.toml file.

It would be nice, if one could completely get rid of the .python-version file.
The used Python version should be in the pyproject.toml file and the uv.lock file.

Because when I set uv up with a local Python version in a project - I usually want that everybody who recreates my project should also have the same Python version.

Flags like uv sync --no-python could prevent the Python version to be recreated.

Or does the Python version not have any space in the pyproject.toml styles? Well I guess this might have been the reason why one decided to have an extra file .python-version for this?

Ideally, one should need only one file uv.lock to perfectly recreate an environment.

Flags could determine whether one wants to update uv.lock or pyproject.toml or include the Python system for sync-ing or not.

[juergsch]

I fully support the idea of: "completely get rid of the .python-version file." and include it in uv.lock. That would improve simplicity and consistency.