# How to use uv to speed up tox


[tox](https://pydevtools.com/handbook/reference/tox.md) spends most of its time creating virtual environments and installing dependencies. The [tox-uv](https://pydevtools.com/handbook/reference/tox-uv.md) plugin replaces both pip and virtualenv with [uv](https://pydevtools.com/handbook/reference/uv.md), cutting that overhead without changing how you write `tox.ini` or run your test matrix.

> [!NOTE]
> This guide requires tox 4.40 or later. Run `tox --version` to check.

## Install tox with tox-uv

The recommended approach installs tox and the plugin together as a [uv tool](https://pydevtools.com/handbook/how-to/how-to-install-python-cli-tools-without-python.md):

```bash
uv tool install tox --with tox-uv
```

This gives you a `tox` command backed by uv. The plugin activates automatically; no changes to `tox.ini` are needed.

If you already have tox installed via pip:

```bash
pip install tox-uv
```

> [!TIP]
> The `tox-uv` package bundles a uv binary so it works even if uv is not on your PATH. In containers where uv is already installed, use `tox-uv-bare` instead to avoid the duplicate binary.

## Verify it's working

Run any tox environment and watch the output. You should see uv commands instead of pip:

```bash
tox -e py313
```

Look for lines like `uv venv` and `uv pip install` in the output. If you see `virtualenv` and `pip install` instead, the plugin is not active. Confirm it is installed in the same environment as tox:

```bash
tox --list-plugins
```

The output should include entries starting with `tox-uv-bare`.

## Combine with parallel execution

tox can run environments concurrently. Pair this with tox-uv for the biggest speed gains on multi-version test matrices:

```bash
tox p
```

This runs all environments in `envlist` in parallel, each using uv for environment creation and dependency installation. On a project with four Python versions and a dozen test dependencies, this combination can reduce a full tox run from minutes to seconds.

To limit parallelism (useful in CI where resources are constrained):

```bash
tox p -o --parallel 2
```

## Use uv's Python downloads

tox-uv uses uv's built-in Python discovery, which means uv can download Python versions on demand if they are not already installed on your system. A `tox.ini` like this works without pre-installing Python 3.11 or 3.12:

```ini
[tox]
envlist = py311,py312,py313
```

If tox cannot find Python 3.11 on the system, uv fetches and installs it automatically.

## Control dependency resolution

tox-uv exposes uv's resolution strategies through the `uv_resolution` setting. This is useful for testing against your lowest supported dependency versions:

```ini
[testenv]
uv_resolution = lowest
```

Valid values are `highest` (the default), `lowest`, and `lowest-direct`.

## Fall back to pip for a single run

If you need to bypass tox-uv temporarily (to debug a uv-specific issue, for example), pass the `--runner` flag:

```bash
tox --runner virtualenv r -e py313
```

This runs the specified environment using the standard virtualenv and pip backend.

## 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.
- [tox reference page](https://pydevtools.com/handbook/reference/tox.md)
- [uv reference page](https://pydevtools.com/handbook/reference/uv.md)
- [How to test against multiple Python versions using uv](https://pydevtools.com/handbook/how-to/how-to-test-against-multiple-python-versions-using-uv.md)
- [tox-uv reference page](https://pydevtools.com/handbook/reference/tox-uv.md)
- [tox parallel mode documentation](https://tox.wiki/en/stable/user_guide.html#parallel-mode)