---
id: nox-uv
version: "0.8.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# nox-uv — Facilitate nox integration with uv for Python projects

License: permissive · Maintenance: active · Downloads: 247.0K/mo

## What it is and what it does

nox-uv bridges nox (a Python test automation tool) and uv (a fast Python package manager) by providing a drop-in replacement for nox's @session decorator that installs dependencies from a uv lockfile instead of resolving them at runtime. This ensures that all developers and CI systems run tests against identical dependency versions, eliminating the "works on my machine" problem.

The package adds parameters to the session decorator—uv_groups, uv_extras, uv_only_groups, and others—that let you specify which dependency groups and optional dependencies from your pyproject.toml should be installed into each test session. It uses uv sync under the hood, which is faster than pip and respects the locked versions in uv.lock. By default it also validates that the lockfile is up to date, catching cases where dependencies have drifted.

Use it for:

- Run test suites across multiple Python versions (3.10–3.14) with locked dependencies to ensure reproducible CI results.
- Separate development dependency groups (lint, type-check, test) in nox sessions without manual version management.
- Validate that uv.lock stays synchronized with pyproject.toml during development and CI runs.
- Speed up test session setup by using uv's faster dependency resolution instead of pip.
- Manage optional dependencies and workspace packages in uv-based monorepos via nox sessions.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

nox-uv replaces nox's standard session decorator to install dependencies from a uv lockfile, ensuring reproducible test and development environments across Python versions.

Yes. If you use nox for test automation and uv for dependency management, nox-uv is the natural integration layer—it's lightweight, actively maintained, has no known vulnerabilities, and solves the real problem of keeping lockfile-based environments synchronized across test sessions. Install it if you want reproducible, fast test runs; skip it if you're not using both nox and uv.

## Install

pip install nox-uv
uv add nox-uv
poetry add nox-uv

## Installing nox-uv

Before you install: Low friction: pure Python wheel with a single runtime dependency on nox. Actively maintained as of May 2026, with recent releases and no known vulnerabilities.

License in practice: MIT license permits unrestricted use, modification, and distribution in both open and closed projects.

Quickstart:

# Install: uv add --group nox nox-uv
# In noxfile.py:
from nox import Session, options
from nox_uv import session

options.default_venv_backend = "uv"

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

Requires nox and uv to be installed; requires a uv.lock file in the project.

Verify before relying:

- Whether uv.lock validation (uv_sync_locked parameter) incurs meaningful performance overhead in CI pipelines.
- Compatibility guarantees with nox versions prior to the package's first release (2025-04-05).

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 247.0K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

nox uv integration, lockfile-based session management, reproducible test environments, uv dependency resolution with nox, nox venv backend uv, python testing with lockfiles, test-automation, dependency-locking, uv-integration

[View on SkillFed](https://skillfed.io/packages/nox-uv) · [View on PyPI](https://pypi.org/project/nox-uv/)