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

Tool	Install	Pin per project	Speed
uv python	`uv python install`	`.python-version`	Fast
pyenv	`pyenv install`	`.python-version`	Moderate
deadsnakes PPA	`apt install python3.14`	Manual	System-wide
asdf	`asdf install python`	`.tool-versions`	Moderate

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

Alternative	Use When	Don't Use When
Docker per version	Exact prod reproduction	Fast local iteration
Nix/devcontainers	Entire team identical envs	Simple single-version apps
System packages only	Server deployment images	Local development

FAQs

uv python vs pyenv - which should I use?

uv python is faster (pre-built binaries) and integrates with uv workflows. pyenv has broader plugin ecosystem. New projects: uv.

How do I check the active Python version?

python --version or uv run python --version inside a project.

Can I run 3.14 code on 3.13?

Only if you avoid 3.14-only syntax and APIs. Test on 3.13 explicitly.

What file pins the version?

.python-version (uv/pyenv), pyproject.toml requires-python, or .tool-versions (asdf).

How do I upgrade the project Python version?

Install the new version, update .python-version, update requires-python, recreate the venv, and run tests.

Do I need multiple versions for libraries?

Yes. Libraries should test against every version in requires-python.

How does free-threaded Python 3.14 fit?

Install 3.14t variant with uv for no-GIL testing. Most apps still use the default build.

Can CI use uv to install Python?

Yes: uv python install 3.14 in GitHub Actions without setup-python.

What about Windows?

uv provides Windows binaries. pyenv-win is the Windows pyenv port.

How do I list installed versions?

uv python list or pyenv versions.

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+.

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

Tool	Install	Pin per project	Speed
uv python	`uv python install`	`.python-version`	Fast
pyenv	`pyenv install`	`.python-version`	Moderate
deadsnakes PPA	`apt install python3.14`	Manual	System-wide
asdf	`asdf install python`	`.tool-versions`	Moderate

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

Alternative	Use When	Don't Use When
Docker per version	Exact prod reproduction	Fast local iteration
Nix/devcontainers	Entire team identical envs	Simple single-version apps
System packages only	Server deployment images	Local development

FAQs

uv python vs pyenv - which should I use?

uv python is faster (pre-built binaries) and integrates with uv workflows. pyenv has broader plugin ecosystem. New projects: uv.

How do I check the active Python version?

python --version or uv run python --version inside a project.

Can I run 3.14 code on 3.13?

Only if you avoid 3.14-only syntax and APIs. Test on 3.13 explicitly.

What file pins the version?

.python-version (uv/pyenv), pyproject.toml requires-python, or .tool-versions (asdf).

How do I upgrade the project Python version?

Install the new version, update .python-version, update requires-python, recreate the venv, and run tests.

Do I need multiple versions for libraries?

Yes. Libraries should test against every version in requires-python.

How does free-threaded Python 3.14 fit?

Install 3.14t variant with uv for no-GIL testing. Most apps still use the default build.

Can CI use uv to install Python?

Yes: uv python install 3.14 in GitHub Actions without setup-python.

What about Windows?

uv provides Windows binaries. pyenv-win is the Windows pyenv port.

How do I list installed versions?

uv python list or pyenv versions.

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+.

Managing Python Versions

Search Documentation

Managing Python Versions