How to change the python version of a uv project

There are two primary ways Python versions are controlled in a uv project:

1. Project requirement in pyproject.toml (requires-python = ">=3.X")
2. Pinned version in .python-version file

Changing the Python Version

Option 1: Update the Project Requirements

To change your project’s Python version requirements permanently, edit your pyproject.toml file:

[project]
# Change this line to your desired Python requirement
requires-python = ">=3.11"

This approach changes the project’s baseline Python requirement.

Option 2: Pin a Specific Python Version

To set the default Python version for your project:

$ uv python pin 3.12

This updates the .python-version file, which uv and other tools (like pyenv) will respect. The pinned version must satisfy your project’s requires-python constraint.

Option 3: Override for a Single Command

To use a specific Python version temporarily:

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

This overrides version settings for the current command only, without modifying any files.