# How to Test Against Multiple Python Versions Using uv


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](https://pydevtools.com/handbook/reference/uv.md) makes this straightforward: it downloads Python versions on demand, so there is no need to install them yourself.

## Prerequisites

- [uv installed](https://docs.astral.sh/uv/getting-started/installation/) on your system
- A Python project with [pytest](https://pydevtools.com/handbook/reference/pytest.md) configured as a dependency (see [Setting up testing with pytest and uv](https://pydevtools.com/handbook/tutorial/setting-up-testing-with-pytest-and-uv.md))

## Run Tests Against a Single Alternate Version

Pass `--python` to select a specific Python version:

```bash
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:

```bash
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](https://just.systems), add a recipe:

```just
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:

```bash
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:

```bash
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](https://github.com/astral-sh/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:

```toml
[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](https://pydevtools.com/handbook/reference/tox.md) with the [tox-uv](https://pydevtools.com/handbook/reference/tox-uv.md) plugin integrates tox's matrix support with uv's fast dependency resolution
- [nox](https://pydevtools.com/handbook/reference/nox.md) gives you a Python-scripted session runner that pairs well with uv through [nox's uv backend](https://nox.thea.codes/en/stable/config.html#configuring-a-session-s-virtualenv)

## See Also

- [Setting up GitHub Actions with uv](https://pydevtools.com/handbook/tutorial/setting-up-github-actions-with-uv.md) for running multi-version tests in CI
- [How to run tests using uv](https://pydevtools.com/handbook/how-to/how-to-run-tests-using-uv.md) for basic test execution
- [uv documentation on Python versions](https://docs.astral.sh/uv/concepts/python-versions/)

## Learn more

- [uv: A Complete Guide](https://pydevtools.com/handbook/explanation/uv-complete-guide.md) covers what uv does, how fast it is, the core workflows, and recent releases.