nox

You can use parametrization to select which Python interpreters to run a session against. This can be done via the @nox.parametrize decorator or by passing a list of versions directly to the @nox.session decorator.

Using @nox.parametrize is particularly useful when you need to implement complex logic to exclude certain combinations (e.g., preventing a specific dependency from running on an older Python version).

# Using @nox.parametrize
@nox.session
@nox.parametrize("python", ["3.10", "3.11", "3.12"])
def tests(session):
    ...

# Using @nox.session argument
@nox.session(python=["3.10", "3.11", "3.12"])
def tests(session):
    ...

# Complex exclusion logic
@nox.session
@nox.parametrize(
    "python,dependency",
    [
        (python, dependency)
        for python in ("3.10", "3.11", "3.12")
        for dependency in ("1.0", "2.0")
        if (python, dependency) != ("3.10", "2.0")
    ],
)
def tests(session, dependency):
    ...

You can use the nox --json -l command to list all available sessions in JSON format. This allows you to dynamically generate a GitHub Actions matrix so that each Nox session runs as a separate job.

Example GitHub Actions workflow snippet:

jobs:
  generate-jobs:
    runs-on: ubuntu-latest
    outputs:
      session: ${{ steps.set-matrix.outputs.session }}
    steps:
    - uses: actions/checkout@v3
    - uses: wntrblm/nox@main
    - id: set-matrix
      shell: bash
      run: echo session=$(nox --json -l | jq -c '[.[].session]') | tee --append $GITHUB_OUTPUT
  checks:
    name: Session ${{ matrix.session }}
    needs: [generate-jobs]
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        session: ${{ fromJson(needs.generate-jobs.outputs.session) }}
    steps:
    - uses: actions/checkout@v3
    - uses: wntrblm/nox@main
    - run: nox -s "${{ matrix.session }}"

If you use uv to lock dependencies, you can integrate it into your Nox sessions. You can either manually run uv sync within a session or use the nox-uv package to reduce boilerplate.

Manual uv sync approach

Set the venv_backend to "uv" and use session.run_install to sync dependencies into the Nox virtual environment.

@nox.session(venv_backend="uv")
def tests(session: nox.Session) -> None:
    """
    Run the unit and regular tests.
    """
    session.run_install(
        "uv",
        "sync",
        "--extra=test",
        "--no-default-extras",
        f"--python={session.virtualenv.location}",
        env={"UV_PROJECT_ENVIRONMENT": session.virtualenv.location},
    )
    session.run("pytest", *session.posargs)

Using nox-uv for simplified dependency groups

The nox-uv package allows you to specify uv_groups or uv_only_groups directly in the session decorator to automatically handle syncing specific dependency groups.

#!/usr/bin/env -S uv run --script --quiet

# /// script
# dependencies = ["nox", "nox-uv"]
# ///

import nox
import nox_uv

nox.options.default_venv_backend = "uv"

@nox_uv.session(
    python=["3.10", "3.11", "3.12", "3.13"],
    uv_groups=["test"],
)
def test(s: nox.Session) -> None:
    """`uv sync` main dependencies and the `test` dependency group."""
    s.run("python", "-m", "pytest")

@nox_uv.session(uv_groups=["type_check"])
def type_check(s: nox.Session) -> None:
    """`uv sync` main dependencies and the `type_check` dependency group."""
    s.run("mypy", "src")

@nox_uv.session(uv_only_groups=["lint"])
def lint(s: nox.Session) -> None:
    """`uv sync` only the `lint` dependency group."""
    s.run("ruff", "check", ".")
    s.run("ruff", "format", "--check", ".")

if __name__ == "__main__":
    nox.main()

To get an accurate coverage report across a matrix of Python versions, follow these three phases:

1. Erase: Remove stale coverage data from previous runs.
2. Measure: Run tests for each Python version, saving the data to a unique file (e.g., .coverage.3.10).
3. Report: Combine the per-version files into a single report.

Use the requires argument in @nox.session to ensure the correct order of execution.

import nox

PYPROJECT = nox.project.load_toml("pyproject.toml")
PYTHON_VERSIONS = nox.project.python_versions(PYPROJECT)


@nox.session(default=False)
def coverage_erase(session: nox.Session) -> None:
    """Remove data left by an earlier coverage run."""
    session.install("coverage[toml]")
    session.run("coverage", "erase")


@nox.session(
    python=PYTHON_VERSIONS,
    default=False,
    requires=["coverage_erase"],
)
def tests(session: nox.Session) -> None:
    """Measure tests independently for each supported Python version."""
    session.install("coverage[toml]", "--group=test", ".")
    session.run(
        "coverage",
        "run",
        "-m",
        "pytest",
        *session.posargs,
        env={"COVERAGE_FILE": f".coverage.{session.python}"},
    )


@nox.session(requires=["tests"])
def coverage_report(session: nox.Session) -> None:
    """Combine the per-version data and display one report."""
    session.install("coverage[toml]")
    session.run("coverage", "combine")
    session.run("coverage", "report", "--show-missing")

Tags can be assigned to parametrized sessions to allow for filtered execution (e.g., nox --tags quick). You can assign tags using the tags argument in @nox.parametrize or by using nox.param(..., tags=['tag1']).

For highly complex tagging logic, you can pass a generator to @nox.parametrize that yields nox.param objects containing the desired tags.

# Using tags in @nox.parametrize
@nox.session
@nox.parametrize('dependency',
    ['1.0', '2.0'],
    tags=[['old'], ['new']])
@nox.parametrize('database',
    ['postgres', 'mysql'],
    tags=[['psql'], ['mysql']])
def tests(session, dependency, database):
    ...

# Using nox.param with tags
@nox.session
@nox.parametrize('dependency', [
    nox.param('1.0', tags=['old']),
    nox.param('2.0', tags=['new']),
])
@nox.parametrize('database', [
    nox.param('postgres', tags=['psql']),
    nox.param('mysql', tags=['mysql']),
])
def tests(session, dependency, database):
    ...

# Using a generator for sophisticated tagging
def generate_params():
    for dependency in ["1.0", "1.1", "2.0"]:
        for database in ["sqlite", "postgresql", "mysql"]:
            tags = []
            if dependency == "2.0" and database == "sqlite":
                tags.append("quick")
            if dependency == "2.0" or database == "sqlite":
                tags.append("standard")
            yield nox.param(dependency, database, tags=tags)

@nox.session
@nox.parametrize(["dependency", "database"], generate_params())
def tests(session, dependency, database):
    ...