Awesome
tox-uv
tox-uv is a tox
plugin, which replaces virtualenv
and pip with uv
in your tox
environments. Note that you
will get both the benefits (performance) or downsides (bugs) of uv
.
- How to use
- tox environment types provided
- uv.lock support
- Environment creation
- Package installation <!--te-->
How to use
Install tox-uv
into the environment of your tox, and it will replace virtualenv
and pip
for all runs:
uv tool install tox --with tox-uv # use uv to install
tox --version # validate you are using the installed tox
tox r -e py312 # will use uv
tox --runner virtualenv r -e py312 # will use virtualenv+pip
tox environment types provided
This package will provide the following new tox environments:
uv-venv-runner
is the ID for the tox environments runner for environments not using a lock file.uv-venv-lock-runner
is the ID for the tox environments runner for environments usinguv.lock
(note we can’t detect the presence of theuv.lock
file to enable this because that would break environments not using the lock file - such as your linter).uv-venv-pep-517
is the ID for the PEP-517 packaging environment.uv-venv-cmd-builder
is the ID for the external cmd builder.
uv.lock support
If you want for a tox environment to use uv sync
with a uv.lock
file you need to change for that tox environment the
runner
to uv-venv-lock-runner
. Furthermore, should in such environments you use the extras
config to instruct uv
to install the specified extras, for example:
[testenv:fix]
description = run code formatter and linter (auto-fix)
skip_install = true
deps =
pre-commit-uv>=4.1.1
commands =
pre-commit run --all-files --show-diff-on-failure
[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
In this example:
fix
will use theuv-venv-runner
and useuv pip install
to install dependencies to the environment.type
will use theuv-venv-lock-runner
and useuv sync
to install dependencies to the environment without any extra group.dev
will use theuv-venv-lock-runner
and useuv sync
to install dependencies to the environment with thedev
,test
andtype
extra groups.
Note that when using uv-venv-lock-runner
, all dependencies will come from the lock file, controlled by extras
.
Therefore, options like deps
are ignored (and all others
enumerated here as Python run flags).
extras
A list of string that selects, which extra groups you want to install with uv sync
. By default, it is empty.
with_dev
A boolean flag to toggle installation of the uv
development dependencies. By default, it is false.
dependency_groups
Specify PEP 735 – Dependency Groups to install.
uv_sync_flags
A list of strings, containing additional flags to pass to uv sync (useful because some flags are not configurable via environment variables). For example, if you want to install the package in non editable mode and keep extra packages installed into the environment you can do:
uv_sync_flags = --no-editable, --inexact
External package support
Should tox be invoked with the --installpkg
flag
(the argument must be either a wheel or source distribution) the sync operation will run with --no-install-project
and uv pip install
will be used afterward to install the provided package.
Environment creation
We use uv venv
to create virtual environments. This process can be configured with the following options:
uv_seed
This flag, set on a tox environment level, controls if the created virtual environment injects pip
, setuptools
and
wheel
into the created virtual environment or not. By default, it is off. You will need to set this if you have a
project that uses the old legacy-editable mode, or your project doesn’t support the pyproject.toml
powered isolated
build model.
uv_python_preference
This flag, set on a tox environment level, controls how uv
select the Python interpreter.
By default, uv
will attempt to use Python versions found on the system and only download managed interpreters when
necessary. However, It is possible to adjust uv
's Python version selection preference with the
python-preference option.
Package installation
We use uv pip
to install packages into the virtual environment. The behavior of this can be configured via the
following options:
uv_resolution
This flag, set on a tox environment level, informs uv
of the desired resolution strategy:
highest
- (default) selects the highest version of a package satisfying the constraints.lowest
- install the lowest compatible versions for all dependencies, both direct and transitive.lowest-direct
- opt for the lowest compatible versions for all direct dependencies, while using the latest compatible versions for all transitive dependencies.
This is an uv
specific feature that may be used as an alternative to frozen constraints for test environments if the
intention is to validate the lower bounds of your dependencies during test executions.