How to fix Python version incompatibility errors in uv

Understanding the Error

When you see an error like this:

error: The Python request from `.python-version` resolved to Python 3.9.1, which is incompatible with the project's Python requirement: `>=3.10`. Use `uv python pin` to update the `.python-version` file to a compatible version.

This means:

1. Your project requires Python 3.10 or newer (specified in pyproject.toml)
2. Your .python-version file is requesting Python 3.9.1
3. This version conflict prevents uv from proceeding

Solution Options

Option 1: Update the .python-version File

The simplest approach is to follow uv’s suggestion to update the .python-version file, e.g.,

$ uv python pin 3.11

This will update the .python-version file to use Python 3.10, the minimum version compatible with your project.

Option 2: Override the Python Version for a Single Command

If you don’t want to update the pinned version permanently, you can override it for a single command:

$ uv run --python 3.10 your_command

Option 3: Update Your Project’s Requirements

If you need to maintain Python 3.9.1 compatibility, you can modify your project’s requirements in pyproject.toml:

[project]
# Change this line
requires-python = ">=3.9.1"

$ uv python list

$ uv python install 3.10