Nox-UV Integration

0.7.1 · active · verified Thu Apr 16

Nox-UV facilitates the integration of `uv`, a fast Python package installer and resolver, into `nox` sessions. It streamlines dependency management and session setup for testing, linting, and other development tasks, leveraging `uv`'s performance benefits. The current version is 0.7.1, and the library maintains an active development pace with frequent updates.

Common errors

```
uv: command not found
```
cause The `uv` executable is not installed or not available in the system's PATH.

fix Install `uv` using `pip install uv` (if you have pipx) or `cargo install uv`. Ensure its installation directory is in your PATH.
```
NameError: name 'uvsession' is not defined
```
cause The `uvsession` decorator was not correctly imported from `nox_uv`.

fix Add `from nox_uv import uvsession` to the top of your `noxfile.py`.
```
nox.session must be passed as a decorator.
```
cause You are using `uvsession` as a regular function call instead of a decorator.

fix Ensure `@uvsession` is placed directly above your session function definition (e.g., `@uvsession(...) def mysession(...)`).
```
nox.virtualenv.VirtualEnv.install: uv is not a valid dependency name or path.
```
cause You might be trying to install `uv` itself using `session.install('uv')` inside a `nox-uv` session. `uv` needs to be globally available or managed outside the specific session.

fix `uv` is expected to be present in the environment where Nox runs. Do not attempt to install `uv` *within* a `nox-uv` managed session.

Warnings

gotcha The `uv` executable must be installed and accessible in the system's PATH or within the Nox virtual environment. `nox-uv` is a bridge, not a `uv` installer.
Fix: Install `uv` globally (`pip install uv` or `cargo install uv`) or ensure it's part of your base Nox environment setup.
breaking Handling of project `extras` changed significantly in v0.3.0 (removed arbitrary extras) and was refined in v0.7.0 (allowing exclusion of specific groups). Old `session.install` calls might behave differently.
Fix: Review your `session.install` calls involving `extras` (e.g., `.[dev,test]`). Consult the documentation for the correct syntax for your `nox-uv` version, especially regarding exclusions.
gotcha From v0.7.1, a `uv_quiet` option was added to suppress `uv sync` output for cleaner logs. If you're missing this option, you're on an older version.
Fix: Upgrade to `nox-uv` v0.7.1 or higher to use the `uv_quiet=True` option in your `@uvsession` decorator.
gotcha For scenarios where the current project should *not* be installed into the session's environment, use `uv_no_project_install=True`.
Fix: If upgrading to v0.6.0 or later, consider adding `uv_no_project_install=True` to your `@uvsession` decorator if your `session.install(".")` or `session.install("-e", ".")` calls are unintentional for that session.

Install

pip install nox-uv Install Nox-UV

Imports

uvsession
wrong:
```
import nox_uv.uvsession
```
correct:
```
from nox_uv import uvsession
```
The `uvsession` decorator is the primary entry point and is directly imported from the top-level package.

Quickstart

Create a `noxfile.py` in your project root. The `uvsession` decorator replaces `nox.session` and automatically uses `uv` for package management within the session. The `session.install` command will then utilize `uv`.

import nox
from nox_uv import uvsession

@uvsession(python=["3.9", "3.10", "3.11", "3.12"])
def test(session: uvsession):
    # Installs project and test dependencies using uv
    session.install("-e", ".[test]")
    session.run("pytest", *session.posargs)

@uvsession(python="3.12")
def lint(session: uvsession):
    # Installs ruff using uv
    session.install("ruff")
    session.run("ruff", "check", ".")
    session.run("ruff", "format", "--check", ".")

view raw JSON →