uv Python Version Management

Purpose

Discover, install, and manage Python versions across your projects and tools. Ensure consistent Python versions within teams and easily test across multiple versions.

Quick Start

Find and pin a Python version for your project:

# See what Python versions are available
uv python list

# Install a specific version
uv python install 3.12

# Pin it for your project
uv python pin 3.12

# Verify
cat .python-version

Now anyone using this project automatically uses Python 3.12.

Instructions

Step 1: Understand Python Version Management

uv helps with three related tasks:

Python Discovery: Find what versions are available

uv python list        # Show installed and available versions

Python Installation: Install specific versions

uv python install 3.12

Project Pinning: Ensure team uses same version

uv python pin 3.12    # Create .python-version file

Step 2: Discover Available Python Versions

List all known versions:

uv python list

Output example:

3.9.19   (installed)
3.10.14  (installed)
3.11.7   (installed)
3.12.1   (installed) ← Currently in use
3.13.0rc1
3.13.0

See only installed:

uv python list --only-installed

Find latest of a version:

uv python list | grep "3.12"

Step 3: Install Python Versions

Install specific version:

uv python install 3.12          # Latest 3.12.x
uv python install 3.12.1        # Exact version
uv python install 3.11.5        # Older version for testing

Install multiple versions:

uv python install 3.11 3.12 3.13

This is automated - no manual compilation needed.

Step 4: Pin Project Python Version

Create .python-version file:

cd my-project
uv python pin 3.12
cat .python-version
# Output: 3.12

What this does:

Creates .python-version file in project root
Any uv command in that directory uses Python 3.12
Team members automatically get same version
Commit to git for consistency

Pin specific patch version:

uv python pin 3.12.1

Step 5: Run Tools with Specific Python

Test code with different Python versions:

uvx --python 3.10 pytest tests/
uvx --python 3.11 pytest tests/
uvx --python 3.12 pytest tests/

Useful for:

Testing backward compatibility
Ensuring minimum Python requirement works
Validating code on pre-release versions

Step 6: Python Versions in CI/CD

GitHub Actions with matrix:

strategy:
  matrix:
    python-version: ["3.10", "3.11", "3.12", "3.13"]
steps:
  - uses: astral-sh/setup-uv@v6
  - run: uv python install ${{ matrix.python-version }}
  - run: uv sync --all-groups
  - run: uv run pytest

GitLab CI with matrix:

test:
  parallel:
    matrix:
      - PYTHON_VERSION: ["3.10", "3.11", "3.12"]
  image: python:${PYTHON_VERSION}
  before_script:
    - uv python install ${PYTHON_VERSION}
  script:
    - uv sync --all-groups
    - uv run pytest

Step 7: Handle Pre-Release Versions

Check for pre-release versions:

uv python list | grep rc
uv python list | grep alpha
uv python list | grep beta

Install pre-release:

uv python install 3.13.0rc1

Pin pre-release for testing:

uv python pin 3.13.0rc1

Examples

Example 1: Find and Install Python 3.12

# See what's available
uv python list

# Find Python 3.12
uv python list | grep "3.12"

# Install it
uv python install 3.12

# Verify installation
python --version

Example 2: Project Setup with Pinned Version

# Create new project
uv init my-app
cd my-app

# Pin to Python 3.12
uv python pin 3.12

# Team member clones and uses it
cd my-app                 # Automatically uses 3.12
python --version          # Python 3.12.1

Example 3: Test Backward Compatibility

# Test with minimum supported version
uvx --python 3.10 pytest tests/

# Test with current version
uvx --python 3.12 pytest tests/

# Test with pre-release
uvx --python 3.13.0rc1 pytest tests/

# All run without installing Python versions globally

Example 4: CI/CD Matrix Testing

# .github/workflows/test.yml
name: Tests
on: [push]

jobs:
  test:
    strategy:
      matrix:
        python-version: ["3.10", "3.11", "3.12", "3.13"]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v6
      - run: uv python install ${{ matrix.python-version }}
      - run: uv sync --all-groups
      - run: uv run pytest

Example 5: Docker Build with Pinned Version

FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
WORKDIR /app
COPY .python-version pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev
COPY . .
CMD ["python", "-m", "myapp"]

Example 6: Legacy Project Migration

# Old project on Python 3.9
cd legacy-project

# Check current version
python --version          # Python 3.9.13

# Upgrade to 3.12
uv python install 3.12
uv python pin 3.12

# Test with new version
uv run pytest

# Commit for team
git add .python-version
git commit -m "Upgrade to Python 3.12"

Requirements

uv installed (install: curl -LsSf https://astral.sh/uv/install.sh | sh)
Internet connection (to download Python versions)
Disk space (each Python version ~100-200 MB)
Administrator access (on Windows, might need for installation)

uv-python-version-management