How to change the python version of a uv project

A uv project tracks Python versions in two places: the .python-version file pins the development interpreter (e.g., 3.12), and requires-python in pyproject.toml declares which versions the project supports (e.g., >=3.11). The pinned version must satisfy the requires-python constraint, or uv will report an incompatibility error.

Pin a different development interpreter

$ uv python pin 3.12

This writes 3.12 to .python-version, which uv reads on every command. If that version isn’t installed locally, uv downloads it automatically.

Then re-sync so the virtual environment picks up the new interpreter:

$ uv sync

Change the supported Python versions

Edit requires-python in pyproject.toml:

[project]
requires-python = ">=3.11"

Then regenerate the lockfile and re-sync:

$ uv lock
$ uv sync

uv lock re-resolves all dependencies against the new constraint. uv sync updates the virtual environment to match.

Use a different version for a single command

Pass --python to override both .python-version and requires-python for one invocation:

$ uv run --python 3.10 python -c "import sys; print(sys.version)"

Related

• What is a .python-version file?
• How to install Python with uv
• How to fix Python version incompatibility errors in uv
• How do pyenv and uv compare for Python interpreter management?