Nox

2026.2.9 · active · verified Thu Apr 09

Nox is a command-line tool that automates development tasks like testing and linting across multiple Python environments. It utilizes a standard Python file (`noxfile.py`) for configuration, creating isolated virtual environments for each defined session. This approach provides programmatic control and reproducibility, installing specified dependencies and running commands within each isolated environment. As of version 2026.2.9, Nox is actively maintained with a regular release cadence, often following a calendar versioning scheme.

Warnings

breaking The library's package name changed from `nox-automation` to `nox`, and the configuration file from `nox.py` to `noxfile.py`. Support for Python 2.7 was dropped, and session actions shifted from declarative to imperative.
Fix: Update `pip install` commands to `pip install nox`, rename `nox.py` to `noxfile.py`, and rewrite session configurations to use imperative `session.install()` and `session.run()` calls. Ensure Python 3.5+ is used for Nox itself.
gotcha Nox is designed to be installed globally (or via `pipx`) in your system's Python environment, *not* within a project's virtual environment. It manages its own isolated virtual environments for each session it runs.
Fix: Install `nox` using `pip install nox` (preferably `pipx install nox`) outside of any project-specific virtual environment. Do not add `nox` to your project's `requirements.txt` or `pyproject.toml` dependencies.
gotcha Each Nox session runs in a freshly created, isolated virtual environment. Any dependencies required for a session's commands (e.g., `pytest`, `flake8`) must be explicitly installed within that session using `session.install()`.
Fix: Always include `session.install('your-dependency')` at the beginning of your Nox session functions for all required packages. Do not rely on packages being available from your global environment or other sessions.
breaking When using `uv` as a backend, `uv` version 0.10.0 and later now require the `--clear` flag to clear an environment.
Fix: If encountering issues with `uv` environments not clearing as expected, ensure your `noxfile.py` or `nox` configuration that uses `uv` backend accounts for this change. Nox 2026.2.9 was released to support this `uv` change internally.

Install

pip install nox Install globally with pip
pipx install nox Recommended: Install with pipx for isolated CLI

Imports

nox
```
import nox
```
session
```
@nox.session
```
Decorator used to define a session function in noxfile.py
Session
```
def my_session(session: nox.Session):
```
Type hint for the session object passed to decorated functions

Quickstart

Create a `noxfile.py` in your project root to define test, lint, and format sessions. Nox will automatically create isolated virtual environments for each session, install dependencies, and execute commands. Run `nox` to execute all defined sessions, or `nox -s <session_name>` to run a specific one.

# noxfile.py
import nox

@nox.session(python=["3.9", "3.10", "3.11"])
def tests(session):
    """Run the test suite with pytest."""
    session.install("pytest")
    session.run("pytest", "tests/")

@nox.session
def lint(session):
    """Lint source code with Flake8 and Black."""
    session.install("flake8", "black")
    session.run("flake8", "src/", "tests/", "noxfile.py")
    session.run("black", "--check", "src/", "tests/", "noxfile.py")

# To run these sessions, save the above as noxfile.py in your project root
# and execute 'nox' in your terminal. For specific sessions, use 'nox -s tests' or 'nox -s lint'.
# To run multiple Python versions, nox will create virtualenvs for each specified version.
# Make sure you have python3.9, python3.10, python3.11 interpreters available on your PATH.

view raw JSON →