tox-uv

To use uv sync with a uv.lock file, set the runner to uv-venv-lock-runner. In this mode, all dependencies are managed via the lock file, and the deps configuration option is ignored. You must use the extras option to specify which dependency groups to install.

Example tox.ini configuration:

[testenv:type]
runner = uv-venv-lock-runner
description = run type checker via mypy
commands = mypy {posargs:src}

[testenv:dev]
runner = uv-venv-lock-runner
description = dev environment
extras =
    dev
    test
    type
commands =
    uv pip tree

Depending on your environment, choose one of the two distribution packages:

1. tox-uv (Recommended): A meta package that includes both the plugin and a bundled uv binary. This is best for local development to ensure uv is always available.
2. tox-uv-bare: A plugin-only package without the bundled uv binary. Use this in containerized environments (Docker, Kubernetes) where uv is already pre-installed in the system to avoid redundant downloads.

FROM python:3.12
RUN pip install uv tox tox-uv-bare
# uv is already in the container, no need to bundle it again

To use tox-uv, install it into your tox environment. Once installed, it replaces virtualenv and pip with uv for all runs. You can verify the installation with tox --version and run environments using the uv backend by running tox r -e <env_id>.

# Use uv to install tox with the tox-uv plugin
uv tool install tox --with tox-uv

# Validate installation
tox --version

# Run an environment using uv
tox r -e py312

# Explicitly fallback to virtualenv+pip if needed
tox --runner virtualenv r -e py312

PEP 723 allows Python scripts to declare dependencies inline. When tox-uv is installed, the virtualenv-pep-723 runner is automatically backed by uv. You can also explicitly use runner = uv-venv-pep-723 in your tox.ini.

To disable this automatic behavior and use the standard virtualenv+pip implementation, set the environment variable TOX_UV_NO_PEP723=1.

# tools/check.py content:
# /// script
# requires-python = ">=3.12"
# dependencies = ["requests>=2.31", "rich"]
# ///

[testenv:check]
runner = virtualenv-pep-723
script = tools/check.py

When using uv-venv-lock-runner, you can control which dependency groups are installed using the following keys:

• extras: A list of strings selecting which extra groups to install with uv sync (e.g., extras = ['dev', 'test']).
• dependency_groups: Specifies PEP 735 – Dependency Groups to install in addition to the project and its dependencies (maps to uv sync --group).
• only_groups: Installs only these groups, excluding the project and all other dependencies (maps to uv sync --only-group). Use this for isolated CI tooling.

When using uv-venv-runner, you can control how the source tree package is installed via the package key. Options include:

• skip: Do not install the project.
• wheel: Install as a non-editable wheel.
• editable (default): Install in editable mode.
• uv: Uses uv directly to install the project (bypassing tox's PEP-517 packaging).
• uv-editable: Uses uv directly to install in editable mode.

If uv is installed in a non-standard location or you are testing a custom build, you can explicitly specify the uv binary location using the TOX_UV_PATH environment variable. Otherwise, tox-uv looks for the bundled uv (in the tox-uv package) or searches your system PATH (in tox-uv-bare).

export TOX_UV_PATH=/custom/path/to/uv
tox r

Fine-tune the uv sync command using these configuration keys:

• uv_sync_flags: A list of strings containing additional flags passed to uv sync (e.g., uv_sync_flags = ['--no-editable', '--inexact']).
• uv_sync_locked: A boolean. If true (default), tox-uv calls uv sync --locked. Set to false to allow other flags like --upgrade to work without conflict.
• uv_seed: A boolean (environment level) that controls if pip, setuptools, and wheel are injected into the virtual environment. Default is off.

By default, tox-uv provides a virtualenv-pep-723 environment type. If you need to prevent this environment type from being registered, set the TOX_UV_NO_PEP723 environment variable to true.

export TOX_UV_NO_PEP723=true
tox run

The plugin provides several specialized runner IDs for different use cases:

• uv-venv-runner: For environments not using a lock file (uses uv pip).
• uv-venv-lock-runner: For environments using uv.lock (uses uv sync).
• uv-venv-pep-723: For PEP 723 inline script metadata. Note that virtualenv-pep-723 is also transparently backed by uv if the plugin is installed.
• uv-venv-pep-517: For PEP-517 packaging environments.
• uv-venv-cmd-builder: For external command builders.