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 noxdependency-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.

fromnoximportSession, optionsfromnox_uvimportsessionoptions.default_venv_backend="uv"@session(python=["3.10", "3.11", "3.12", "3.13", "3.14"],uv_groups=["test"],)deftest(s: Session) ->None:
s.run("python", "-m", "pytest")
@session(uv_groups=["type_check"])deftype_check(s: Session) ->None:
s.run("mypy", "src")
@session(uv_only_groups=["lint"])deflint(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 uvdependency-groups
• uv_extras: list of uvoptional-dependencies
• uv_only_groups: list of uvonly-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_packages: list of uvpackages to install, only valid in a uv workspace.
• uv_all_packages: boolean to install all uvpackages, only valid in a uv workspace.
• uv_sync_locked: boolean to validate that uv.lock is up to date
• uv_quiet: boolean to silence uv sync command

Inspiration

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