nox "venv_backend='uv'" / tox-uv Backend Error in CI

By Daniel Zoghalchali·Latchkey

Selecting uv as the virtualenv backend (nox venv_backend="uv", or the tox-uv plugin) needs uv installed and a nox/tox new enough to recognize it. A missing uv binary or an old runner version makes the backend selection fail.

What this error means

A nox session or tox env fails to set up its environment with an error about an unknown/unsupported venv_backend, or uv: command not found. The same config works where uv and a recent nox/tox are installed.

nox > Error: Expected venv_backend one of ('none','virtualenv','conda','mamba','venv','uv'),
but got 'uv' - uv was not found on PATH.

Common causes

uv not installed on the runner

The uv backend shells out to the uv binary. Without uv on PATH, nox/tox cannot create the environment with that backend.

nox/tox too old or plugin missing

uv backend support was added in newer nox; tox needs the tox-uv plugin. An old version or a missing plugin does not recognize the backend.

How to fix it

Install uv (and the tox plugin) first

pip install --upgrade uv nox
# for tox:
pip install tox tox-uv

Select the uv backend correctly

Use the backend per the installed tool’s docs.

import nox

@nox.session(venv_backend="uv")
def tests(session):
    session.install("-e", ".[test]")
    session.run("pytest")

How to prevent it

• Install uv and a recent nox/tox-uv before invoking uv-backed envs.
• Pin the nox/tox (and plugin) versions that support the uv backend.
• Fall back to the venv backend where uv is unavailable.

Frequently asked questions

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation