Nox

Installation and Setup

Install it from PyPI:

• Windows
• Linux + macOS

(venv) PS> py -m pip install nox

(venv) $ python -m pip install nox

Key Features

• Defines functions in noxfile.py using @nox.session decorator.
• Creates isolated environments per session using a selectable backend. It defaults virtualenv, but supports uv, Conda, mamba, micromamba, and venv.
• Runs sessions across multiple Python versions and filters by Python version at the CLI with --python.
• Builds test matrices with nox.parametrize, including readable IDs.
• Filters which sessions run using pytest-style keywords (-k/--keywords) and tags (-t/--tags).
• Reuses environments between runs with --reuse-venv=yes (or -r) to speed up local workflows.
• Supports optional helpers like nox-poetry and nox-uv for tighter integration with Poetry and uv workflows.

Usage

Create a noxfile.py in your project directory and define sessions with an optional list of Python versions:

import nox

@nox.sessionp(python=["3.12", "3.13", "3.14"])
def tests(session):
    session.install("pytest")
    session.run("pytest", "-q")

Run all sessions:

$ nox

List available sessions:

$ nox -l

Select sessions to run:

$ nox -s lint tests

Choose Python versions at the CLI:

$ nox --python 3.12

Reuse environments to speed up local runs:

$ nox --reuse-venv=yes

Switch the default backend, with optional fallbacks:

$ nox --default-venv-backend "uv|virtualenv"