Managing Python Versions

Running multiple Python versions on one machine lets you develop on the latest release, test backward compatibility, and match production interpreters exactly.

Recipe

# uv (recommended)
uv python install 3.13 3.14
uv python pin 3.14
 
# pyenv (alternative)
pyenv install 3.14.0
pyenv local 3.14.0

When to reach for this:

• Testing against Python 3.13 and 3.14 in the same repo
• Matching a production interpreter version locally
• Contributing to libraries with broad requires-python support

Working Example

# Install interpreters
uv python install 3.13 3.14
 
# Pin project to 3.14
cd myproject
uv python pin 3.14
cat .python-version   # 3.14
 
# Test on 3.13 without changing the pin
uv run --python 3.13 pytest
 
# Multi-version CI matrix (GitHub Actions excerpt)

strategy:
  matrix:
    python-version: ["3.13", "3.14"]
steps:
  - uses: actions/setup-python@v5
    with:
      python-version: ${{ matrix.python-version }}
  - run: pip install -e ".[dev]" && pytest

What this demonstrates:

• uv python install downloads interpreters without system package managers
• .python-version pins the default for a directory tree
• uv run --python runs a single command against another version
• CI matrices verify compatibility across supported versions

Deep Dive

How It Works

• uv python stores interpreters in ~/.local/share/uv/python/ and symlinks on demand
• pyenv compiles or downloads interpreters into ~/.pyenv/versions/ and shims python via PATH
• requires-python in pyproject.toml declares the supported range
• tox/nox automate multi-version test runs locally and in CI

Version Selection Tools

Python Notes

# pyproject.toml - declare supported range
[project]
requires-python = ">=3.13"

# tox.ini for local multi-version testing
[tox]
envlist = py313,py314

Gotchas

• System Python for projects - breaks when OS upgrades Python. Fix: always use a project venv with a pinned interpreter.
• .python-version not committed - teammates use different versions. Fix: commit .python-version or document in pyproject.toml.
• Testing only on latest - surprises users on older versions. Fix: CI matrix covering requires-python lower bound.
• pyenv build failures on macOS - missing Xcode CLI tools. Fix: xcode-select --install; or use uv python install (pre-built binaries).
• Mixing pyenv and uv pins - conflicting shims. Fix: standardize on one version manager per project.

Alternatives

FAQs

Related

• uv - The Fast Toolchain - integrated version management
• Environments & Packaging Basics - venv fundamentals
• tox / nox - multi-version test automation
• Environments Best Practices - version policy

Stack versions: This page was written for Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.