nox-uv 0.7.0

Facilitate nox integration with uv for Python projects

Intro

nox-uv is a simple drop-in replacement for nox's @nox.session that installs dependencies constrained by uv's lockfile.

Usage

Add nox-uv as a development dependency. The following example adds it into a nox dependency-group.

uv add --group nox nox-uv

Using the following configuration within pyproject.toml as an example:

[dependency-groups]
nox = [
    "nox-uv",
]
test = [
    "pytest",
    "pytest-cov",
]
type_check = [
    "mypy",
]
lint = [
    "ruff",
]

Within, your noxfile.py:

1. Import session from nox_uv.
2. Set venv_backend to "uv". This can be done globally using options.default_venv_backend = "uv".
3. Use the new uv_* parameters to session to control which dependencies are synced into the session's virtual environment in addition to the project's main dependencies.
   • uv sync is used to install dependencies so that their versions are constrained by uv.lock.
   • By default (configurable with the uv_sync_locked parameter), uv.lock is also validated to be up to date.

from nox import Session, options
from nox_uv import session

options.default_venv_backend = "uv"


@session(
    python=["3.10", "3.11", "3.12", "3.13", "3.14"],
    uv_groups=["test"],
)
def test(s: Session) -> None:
    s.run("python", "-m", "pytest")


@session(uv_groups=["type_check"])
def type_check(s: Session) -> None:
    s.run("mypy", "src")


@session(uv_only_groups=["lint"])
def lint(s: Session) -> None:
    s.run("ruff", "check", ".")
    s.run("ruff", "format", "--check", ".")

[!NOTE] All @session(...) parameters are keywords only, no positional parameters are allowed.

[!NOTE] The default_groups defined in pyproject.toml are not installed by default. The user must explicitly list the desired groups in the uv_groups parameter.

Added parameters

• uv_groups: list of uv dependency-groups
• uv_extras: list of uv optional-dependencies
• uv_only_groups: list of uv only-groups to include. Prevents installation of project dependencies
• uv_all_extras: boolean to install all optional-dependencies from pyproject.toml
• uv_no_extras: list of extras to exclude during install of uv_all_extras
• uv_all_groups: boolean to install all dependency-groups
• uv_no_groups: list of groups to exclude during install of uv_all_groups
• uv_no_install_project: boolean to not install the current project
• uv_sync_locked: boolean to validate that uv.lock is up to date

Inspiration

This is heavily influenced by, but much more limited than, nox-poetry.