# tox-uv: uv backend for tox


tox-uv is a plugin for [tox](https://pydevtools.com/handbook/reference/tox.md) that replaces pip and virtualenv with [uv](https://pydevtools.com/handbook/reference/uv.md). When installed alongside tox, it activates automatically and handles all virtual environment creation and dependency installation using uv's resolver and installer. No changes to `tox.ini` are required for basic usage.

## Installation

The recommended approach installs tox and the plugin together as a uv tool:

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

Two distribution packages exist:

- `tox-uv` bundles a uv binary alongside the plugin. This is the default and works without uv on the system PATH.
- `tox-uv-bare` contains only the plugin. Use this in containers or CI environments where uv is already installed to avoid a duplicate binary.

## Requirements

- tox 4.40 or later (tox-uv does not support tox 3)
- Python 3.10 or later

## How it works

tox-uv registers replacement environment types that tox uses instead of its built-in virtualenv and pip backends:

| Environment type | Purpose |
|---|---|
| `uv-venv-runner` | Default runner for test environments (replaces virtualenv + pip) |
| `uv-venv-lock-runner` | Runner that installs from a `uv.lock` file instead of `deps` |
| `uv-venv-pep-517` | PEP 517 packaging environment |
| `uv-venv-cmd-builder` | External command builder |

The `uv-venv-runner` activates automatically for all environments. The lock runner must be enabled explicitly per environment with `runner = uv-venv-lock-runner`.

## Configuration

tox-uv adds several per-environment settings to `tox.ini`:

| Setting | Description | Default |
|---|---|---|
| `uv_resolution` | Dependency resolution strategy: `highest`, `lowest`, or `lowest-direct` | `highest` |
| `uv_python_preference` | How uv selects the Python interpreter (maps to uv's `python-preference`) | uv default |
| `uv_seed` | Inject pip, setuptools, and wheel into the venv | `false` |
| `uv_sync_flags` | Additional flags passed to `uv sync` (lock runner only) | none |
| `uv_sync_locked` | Pass `--locked` to `uv sync` (lock runner only) | `true` |
| `dependency_groups` | PEP 735 groups to install in addition to the project | none |
| `only_groups` | PEP 735 groups to install instead of the project | none |

### Example: test against lowest supported dependencies

```ini
[testenv]
uv_resolution = lowest
deps =
    pytest
commands =
    pytest {posargs}
```

### Example: use a lockfile

```ini
[testenv:locked]
runner = uv-venv-lock-runner
commands =
    pytest {posargs}
```

When using the lock runner, all dependencies come from `uv.lock`. The `deps` setting is ignored.

## Environment variables

| Variable | Purpose |
|---|---|
| `TOX_UV_PATH` | Override the path to the uv binary (takes precedence over bundled and system uv) |

## uv discovery order

1. `TOX_UV_PATH` environment variable
2. Bundled uv binary (when using the `tox-uv` package)
3. System uv on PATH (when using `tox-uv-bare` or if bundled is not found)

## Python version discovery

tox-uv delegates Python discovery to uv. If a requested Python version (e.g. `py312`) is not installed on the system, uv downloads and installs it automatically. The `uv_python_preference` setting controls whether uv prefers system installations or managed downloads.

## Falling back to pip

To bypass tox-uv for a single run (useful for debugging uv-specific issues):

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

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

## Learn More

- [Do you still need tox or nox if you use uv?](https://pydevtools.com/handbook/explanation/do-you-still-need-tox-or-nox-if-you-use-uv.md) explains when tox (with tox-uv) earns its place over plain `uv run --python`
- [How to use uv to speed up tox](https://pydevtools.com/handbook/how-to/how-to-use-uv-to-speed-up-tox.md)
- [How to replace tox with uv and a Makefile](https://pydevtools.com/handbook/how-to/how-to-replace-tox-with-uv-and-a-makefile.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 reference page](https://pydevtools.com/handbook/reference/tox.md)
- [uv reference page](https://pydevtools.com/handbook/reference/uv.md)
- [How Python tools adopt uv under the hood](https://pydevtools.com/handbook/explanation/how-python-tools-adopt-uv-under-the-hood.md)
- [tox-uv GitHub repository](https://github.com/tox-dev/tox-uv)
- [tox-uv on PyPI](https://pypi.org/project/tox-uv/)