How do I run pytest against a specific Python version with uv?

Run `uv run --python 3.12 pytest`. uv selects the requested Python version, downloads and installs it automatically if it isn't already present, and runs pytest against the project's locked dependencies. The `--python` flag works with any CPython version uv supports, including pre-releases like `3.15.0b1`.

How do I test against multiple Python versions at once?

Loop over the versions you support: `for version in 3.10 3.11 3.12 3.13 3.14; do uv run --python $version pytest; done`. Each iteration runs the full test suite under that Python version, downloading missing interpreters on the fly. For just recipes, wrap the loop in `test-all-pythons:` and exit on the first failure to surface breakage early.

Can uv test against an upcoming Python pre-release?

Yes. Add the upcoming version to your test loop, for example `uv run --python 3.15 pytest`. uv resolves to the latest 3.15 pre-release published by python-build-standalone. Pin a specific pre-release for reproducibility with the full version like `3.15.0b1`. Expect failures: dependencies often lack wheels for new Python versions and may fall back to source builds.

When should I use tox or nox instead of a shell loop?

Reach for tox (with the tox-uv plugin) or nox when the matrix has more than one axis, you need named environments running distinct command sequences (docs, coverage, integration), you want `--lowest` dependency resolution, or CI operators expect a single declarative config file. A shell loop is enough for running the same tests across a handful of Python versions.

How to Test Against Multiple Python Versions Using uv

by Tim Hopper

uv Testing

A library that works on Python 3.11 can break on 3.12 because of removed deprecations, C API changes, or subtle differences in standard library behavior. Catching these failures before your users do requires running tests against each version you support. uv makes this straightforward: it downloads Python versions on demand, so there is no need to install them yourself.

Prerequisites

uv installed on your system
A Python project with pytest configured as a dependency (see Setting up testing with pytest and uv)

Run Tests Against a Single Alternate Version

Pass --python to select a specific Python version:

uv run --python 3.12 pytest

If Python 3.12 is not already installed, uv downloads and installs it automatically. This works with any CPython version uv supports.

Run Tests Against Multiple Versions

Loop over the versions you need:

for version in 3.10 3.11 3.12 3.13 3.14; do
    echo "=== Python $version ==="
    uv run --python $version pytest
done

If you use a justfile, add a recipe:

test-all-pythons:
    #!/usr/bin/env bash
    for version in 3.10 3.11 3.12 3.13 3.14; do
        echo "=== Python $version ==="
        uv run --python $version pytest || exit 1
    done

Run it with:

just test-all-pythons

Test Against an Upcoming Pre-Release

To catch breakage in the next Python before it ships, add the upcoming version to the loop. Python 3.15 reached beta 1 on 7 May 2026 (final release scheduled for October 2026), and uv installs pre-releases with the same command:

for version in 3.13 3.14 3.15; do
    echo "=== Python $version ==="
    uv run --python $version pytest
done

uv run --python 3.15 resolves to whatever 3.15 pre-release python-build-standalone has most recently published. To pin a specific pre-release for reproducibility, use the full version (uv run --python 3.15.0b1 pytest). Expect failures during pre-release testing: dependencies often lack wheels for new Python versions and either fall back to source builds or refuse to install.

Constrain Which Versions to Test

The requires-python field in pyproject.toml declares which Python versions your project supports:

[project]
requires-python = ">=3.10"

uv respects this constraint when resolving dependencies. If you ask uv to run against a version outside this range, it will refuse with an error explaining the conflict. Keep requires-python in sync with the versions you test against.

Alternatives for Complex Test Matrices

A shell loop works well for running the same tests across a few Python versions. For more complex scenarios (testing with different dependency combinations, running in parallel, or generating reports), dedicated test automation tools are a better fit:

tox with the tox-uv plugin integrates tox’s matrix support with uv’s fast dependency resolution
nox gives you a Python-scripted session runner that pairs well with uv through nox’s uv backend