Nox

https://github.com/wntrblm/nox
Admin
Nox is a command-line tool that automates testing in multiple Python environments using a standard...
Tokens:17,725
Snippets:252
Trust Score:8.1
License:Apache-2.0
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install packages with session.install

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Methods for installing packages via pip, including direct installation, requirements files, and local package installation.

```default
session.install('pytest')
session.install('requests', 'mock')
session.install('requests[security]==2.9.1')
```

```default
session.install('-r', 'requirements.txt')
session.install('-r', 'requirements-dev.txt')
```

```default
session.install('.')
# Install in editable mode.
session.install('-e', '.')
```

--------------------------------

### Install Nox for development

Source: https://github.com/wntrblm/nox/blob/main/docs/CONTRIBUTING.md

Install the latest pre-release version of Nox from PyPI to ensure a known-good environment.

```bash
pip install --pre --upgrade nox
```

--------------------------------

### Install external dependencies with run_install

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Use session.run_install for commands that must run during the installation phase, such as building binary extensions.

```python
@nox.session
def tests(session):
    ...
    session.run_install(
        "cmake", "-DCMAKE_BUILD_TYPE=Debug",
        "-S", libfoo_src_dir,
        "-B", build_dir,
        external=True,
    )
    session.run_install(
        "cmake",
        "--build", build_dir,
        "--config", "Debug",
        "--target", "install",
        external=True,
    )
    session.install(".")
    ...
```

--------------------------------

### Install Nox via pip

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Standard installation command for Nox using pip.

```console
python3 -m pip install nox
```

--------------------------------

### run_install

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Executes a command during the install step, useful for prerequisites or custom installation commands. It respects the --install-only and --no-install flags.

```APIDOC
## run_install(*args, env=None, include_outer_env=True, silent=False, success_codes=None, log=True, external=None, stdout=None, stderr=-2, interrupt_timeout=0.3, terminate_timeout=0.2)

### Description
Runs a command in the install step. This method is a variant of run() that executes even when --install-only is specified and returns early if --no-install is used.

### Parameters
- **env** (dict or None) - Optional - A dictionary of environment variables to expose to the command.
- **include_outer_env** (bool) - Optional - Determines if environment variables from the nox invocation should be passed. Default is True.
- **silent** (bool) - Optional - Silence command output unless the command fails. Default is False.
- **success_codes** (list, tuple, or None) - Optional - A list of return codes considered successful. Default is [0].
- **external** (bool) - Optional - If False, programs not in the virtualenv path cause a warning. Default is False.
- **interrupt_timeout** (float or None) - Optional - Seconds to wait after an interrupt signal before sending a terminate signal. Default is 0.3.
- **terminate_timeout** (float or None) - Optional - Seconds to wait after a terminate signal before sending a kill signal. Default is 0.2.
```

--------------------------------

### Command-line execution examples

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Examples of how Nox interprets command-line arguments for the session defined above.

```console
nox
```

```console
pytest test_a.py test_b.py
```

```console
nox -- test_c.py
```

```console
pytest test_c.py
```

--------------------------------

### Use install_and_run_script helper

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

A shorthand method for installing dependencies and running a PEP 723 script.

```python
@nox.session
def peps(session):
    session.install_and_run_script("peps.py")
```

--------------------------------

### Install Tox Converter

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Install the necessary extra to enable tox configuration conversion.

```console
pip install --upgrade nox[tox-to-nox]
```

--------------------------------

### Install Nox

Source: https://github.com/wntrblm/nox/blob/main/README.md

Installation commands for Nox using pipx, pip, or user-site.

```shell
pipx install nox
```

```shell
python3 -m pip install nox
```

```shell
python3 -m pip install --user nox
```

--------------------------------

### Install Nox

Source: https://github.com/wntrblm/nox/blob/main/docs/index.md

Commands to install Nox using pipx or pip.

```bash
pipx install nox
```

```bash
python3 -m pip install nox
```

--------------------------------

### Run basic commands in session

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Install a package and execute a command within the session's virtual environment.

```python
@nox.session
def tests(session):
    session.install("pytest")
    session.run("pytest")
```

--------------------------------

### Run sessions by tag

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Example output when running sessions filtered by the 'style' tag.

```console
* black
* isort
* flake8
```

--------------------------------

### install_and_run_script

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Installs dependencies and executes a specified Python script within the session context.

```APIDOC
## install_and_run_script(script, *args, env=None, include_outer_env=True, silent=False, success_codes=None, log=True, stdout=None, stderr=-2, interrupt_timeout=0.3, terminate_timeout=0.2)

### Description
Install dependencies and run a Python script.

### Parameters
- **script** (str | os.PathLike[str]) - Required - The path to the script to run.
- **args** (str | os.PathLike[str]) - Optional - Arguments to pass to the script.
- **env** (Mapping[str, str | None]) - Optional - Environment variables.
- **include_outer_env** (bool) - Optional - Whether to include the outer environment.
- **silent** (bool) - Optional - Whether to suppress output.
- **success_codes** (Iterable[int]) - Optional - List of codes considered successful.
- **log** (bool) - Optional - Whether to log the execution.
- **stdout** (int | IO[str]) - Optional - Standard output stream.
- **stderr** (int | IO[str]) - Optional - Standard error stream.
- **interrupt_timeout** (float) - Optional - Timeout for interruption.
- **terminate_timeout** (float) - Optional - Timeout for termination.
```

--------------------------------

### Define a noxfile.py

Source: https://github.com/wntrblm/nox/blob/main/docs/index.md

Example configuration file defining sessions for running tests and linting.

```python
import nox

@nox.session
def tests(session):
    session.install('pytest')
    session.run('pytest')

@nox.session
def lint(session):
    session.install('flake8')
    session.run('flake8', '--import-order-style', 'google')
```

--------------------------------

### Session.conda_install

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Invokes conda install to install packages inside the session's environment.

```APIDOC
## Session.conda_install(*args, auto_offline=True, channel='', env=None, include_outer_env=True, silent=None, success_codes=None, log=True, stdout=None, stderr=-2, interrupt_timeout=0.3, terminate_timeout=0.2)

### Description
Installs packages using conda. Detects internet connectivity to automatically add the --offline flag unless auto_offline is set to False.
```

--------------------------------

### Create an instant development environment session

Source: https://github.com/wntrblm/nox/blob/main/docs/cookbook.md

Sets up a local virtual environment and installs project dependencies in editable mode. Uses default=False to prevent accidental execution during standard test runs.

```python
import nox


# It's a good idea to keep your dev session out of the default list
# so it's not run twice accidentally
@nox.session(default=False)
def dev(session: nox.Session) -> None:
    """
    Set up a python development environment for the project at ".venv".
    """

    session.install("virtualenv")

    session.run("virtualenv", ".venv", silent=True)

    # Use the venv's interpreter to install the project along with
    # all its dev dependencies, this ensures it's installed in the right way
    session.run(".venv/bin/pip", "install", "-e", ".[dev]", external=True)
```

--------------------------------

### Run a specific session

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Example output when executing only the lint session.

```console
nox > Running session lint
nox > Creating virtualenv using python3 in .nox/lint
nox > ...
nox > Session lint was successful.
```

--------------------------------

### Session.install

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Invokes pip to install packages inside the session's virtualenv.

```APIDOC
## Session.install(*args, env=None, include_outer_env=True, silent=None, success_codes=None, log=True, external=None, stdout=None, stderr=-2, interrupt_timeout=0.3, terminate_timeout=0.2)

### Description
Installs packages using pip. Supports direct package names, requirements files, and local package installation.
```

--------------------------------

### Install Nox via pip to user site

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Installation command for Nox using the user site to avoid global environment modifications.

```console
python3 -m pip install --user nox
```

--------------------------------

### Install packages with session.conda_install

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Methods for installing packages via conda, including direct installation, requirements files, and local package installation.

```default
session.conda_install('pandas')
session.conda_install('numpy', 'scipy')
session.conda_install('dask==2.1.0', channel='conda-forge')
```

```default
session.conda_install('--file', 'requirements.txt')
session.conda_install('--file', 'requirements-dev.txt')
```

```default
session.install('.', '--no-deps')
# Install in editable mode.
session.install('-e', '.', '--no-deps')
```

--------------------------------

### Skip run commands with install-only

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

The --install-only flag executes only install commands, useful for offline preparation or environment recreation.

```python
@nox.session
def tests(session):
    session.install("pytest")
    session.install(".")
    session.run("pytest")
```

```console
nox --install-only
```

```console
nox > Running session tests
nox > Creating virtualenv using python3.12 in ./.nox/tests
nox > python -m pip install pytest
nox > python -m pip install .
nox > Skipping pytest run, as --install-only is set.
nox > Session tests was successful.
```

--------------------------------

### View expanded sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Example output showing how Nox expands parametrized sessions into individual tasks.

```console
Sessions defined in noxfile.py:

* test(django='1.9')
* test(django='2.0')
```

--------------------------------

### Install dependencies in a session

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Use session.install to manage package dependencies within the session environment.

```python
@nox.session
def tests(session):
    # same as pip install pytest protobuf>3.0.0
    session.install("pytest", "protobuf>3.0.0")
    ...
```

```python
@nox.session
def tests(session):
    # same as pip install -r requirements.txt
    session.install("-r", "requirements.txt")
    ...
```

```python
@nox.session
def tests(session):
    # same as pip install .
    session.install(".")
    ...
```

--------------------------------

### Install Nox via pipx

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Installation command for Nox using pipx for isolated environment management.

```console
pipx install nox
```

--------------------------------

### Run sessions by fix tag

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Example output when running sessions filtered by the 'fix' tag.

```console
* black
* isort
- flake8
```

--------------------------------

### Install packages in conda environment

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Use session.conda_install to manage packages via conda channels.

```python
session.conda_install("pytest", channels=["conda-forge"])
```

--------------------------------

### Define a basic Nox session

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Use the @nox.session decorator to define a session that installs dependencies and runs commands.

```python
import nox

@nox.session
def lint(session):
    session.install("flake8")
    session.run("flake8", "example.py")
```

--------------------------------

### Run uv sync in a Nox session

Source: https://github.com/wntrblm/nox/blob/main/docs/cookbook.md

Uses the uv backend to synchronize dependencies within a Nox virtual environment. Ensure the uv tool is installed and available in the environment.

```python
@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)
```

--------------------------------

### Manage dependencies with nox-uv

Source: https://github.com/wntrblm/nox/blob/main/docs/cookbook.md

Simplifies dependency group management using the nox-uv package. Requires the nox-uv dependency to be installed.

```python
#!/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()
```

--------------------------------

### Nox CLI usage

Source: https://github.com/wntrblm/nox/blob/main/README.md

Common command-line operations for listing, running, and getting help for sessions.

```shell
nox -l/--list
```

```shell
nox --usage test
```

```shell
nox
```

```shell
nox -s/--session test
```

--------------------------------

### Use PEP 440 version specifiers

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Define version ranges to automatically select the first installed interpreter that satisfies the criteria.

```python
@nox.session(python='>=3.14')
def tests(session):
    pass

@nox.session(python='>=3.11,<3.13')
def lint(session):
    pass
```

--------------------------------

### Disable virtualenv creation

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Set python to False to run sessions without a virtual environment. Use session.run with pip if package installation is required.

```python
@nox.session(python=False)
def tests(session):
    pass
```

```python
@nox.session(python=False)
def tests(session):
    session.run("pip", "install", "nox")
```

--------------------------------

### Combine coverage across Python versions

Source: https://github.com/wntrblm/nox/blob/main/docs/cookbook.md

Measures test coverage independently per Python version and combines the results into a single report. Requires coverage[toml] to be installed in the sessions.

```python
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")
```

--------------------------------

### Load dependencies and run script

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Demonstrates loading dependencies from a script file and executing it within a Nox session.

```python
@nox.session
def peps(session):
    requirements = nox.project.load_toml("peps.py")["dependencies"]
    session.install(*requirements)
    session.run("python", "peps.py")
```

--------------------------------

### Install pip packages in conda environment

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Use the --no-deps flag when installing pip packages into a conda environment to avoid dependency conflicts.

```python
session.install("contexter", "--no-deps")
session.install("-e", ".", "--no-deps")
```

--------------------------------

### Reuse virtualenvs without re-installing packages

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Reuses existing virtualenvs while skipping package installation steps. This causes session install methods to return early.

```console
nox -R
nox --reuse-existing-virtualenvs --no-install
nox --reuse-venv=yes --no-install
```

--------------------------------

### View session usage

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Use the --usage command to display the full docstring of a specific session.

```console
$ nox --usage tests
Run the test suite.

The test suite consists of all tests in tests/.
```

--------------------------------

### Enable Fish Autocompletion

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Pipe the registration command to the shell source to enable autocompletion.

```console
register-python-argcomplete --shell fish nox | .
```

--------------------------------

### Configure virtualenv backends

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Specify the backend for virtual environment creation or pass custom parameters to the backend.

```python
@nox.session(venv_backend='venv')
def tests(session):
    pass
```

```python
@nox.session(venv_params=['--no-download'])
def tests(session):
    pass
```

--------------------------------

### List available sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/CONTRIBUTING.md

Display all available test sessions defined in the project.

```bash
nox --list-sessions
```

--------------------------------

### List available Nox sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Run the list command to view all configured sessions, including those with custom names.

```console
$ nox --list
Available sessions:
* custom-name
```

--------------------------------

### run

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Executes a command within the session environment.

```APIDOC
## run(*args, env=None, include_outer_env=True, silent=False, success_codes=None, log=True, external=None, stdout=None, stderr=subprocess.STDOUT, interrupt_timeout=DEFAULT_INTERRUPT_TIMEOUT, terminate_timeout=DEFAULT_TERMINATE_TIMEOUT)

### Description
Runs a command in the session. Overloaded to return bool or str depending on the silent parameter.

### Parameters
- **args** (str | PathLike[str]) - Required - Command and arguments to run.
- **env** (Mapping[str, str | None]) - Optional - Environment variables.
- **silent** (bool) - Optional - If True, returns captured output; if False, returns success status.
```

--------------------------------

### Execute Nox main entry point

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Add this block to the noxfile to enable execution when the file is run as a script.

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

--------------------------------

### List available sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Output showing all sessions defined in the Noxfile.

```console
Sessions defined in noxfile.py:

* test
* lint
* docs

sessions marked with * are selected,
sessions marked with - are skipped.
```

--------------------------------

### Run basic commands

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Commands must be passed as a list of strings rather than a single concatenated string.

```python
session.run('pytest', '-k', 'fast', 'tests/')
session.run('flake8', '--import-order-style=google')
```

```python
session.run('pytest -k fast tests/')
```

--------------------------------

### Run Tox Converter

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Execute the conversion tool in a directory containing a tox.ini file.

```console
tox-to-nox
```

--------------------------------

### Automate project releases with Nox

Source: https://github.com/wntrblm/nox/blob/main/docs/cookbook.md

Uses bump-my-version to handle semver increments and git tagging. Requires user confirmation before proceeding with the release process.

```python
import argparse
import nox

@nox.session
def release(session: nox.Session) -> None:
    """
    Kicks off an automated release process by creating and pushing a new tag.

    Invokes bump-my-version with the posarg selecting the version part.

    Usage:
    $ nox -s release -- [major|minor|patch]
    """
    parser = argparse.ArgumentParser(description="Release a semver version.")
    parser.add_argument(
        "version",
        type=str,
        nargs=1,
        help="The type of semver release to make.",
        choices={"major", "minor", "patch"},
    )
    args: argparse.Namespace = parser.parse_args(args=session.posargs)
    version: str = args.version.pop()

    # If we get here, we should be good to go
    # Let's do a final check for safety
    confirm = input(
        f"You are about to bump the {version!r} version. Are you sure? [y/n]: "
    )

    # Abort on anything other than 'y'
    if confirm.lower().strip() != "y":
        session.error(f"You said no when prompted to bump the {version!r} version.")


    session.install("bump-my-version")

    session.log(f"Bumping the {version!r} version")
    session.run("bump-my-version", "bump", version)

    session.log("Pushing the new tag")
    session.run("git", "push", external=True)
    session.run("git", "push", "--tags", external=True)
```

--------------------------------

### Configure default venv backend via CLI

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Set the default virtual environment backend using command line arguments.

```console
nox -db conda
nox --default-venv-backend conda
```

--------------------------------

### List Available Sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Commands to display all defined sessions or detailed usage information for a specific session.

```console
nox -l
nox --list
nox --list-sessions
```

```console
nox --usage tests
```

--------------------------------

### Run sessions against multiple Python interpreters

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Provide a list of versions to create separate virtual environments for each interpreter.

```python
@nox.session(python=['3.13', '3.14'])
def tests(session):
    pass
```

```python
@nox.session(python=['3.13', '3.14', 'pypy3.11'])
def tests(session):
    pass
```

--------------------------------

### session.run(*args, env=None, include_outer_env=True, silent=False, success_codes=None, log=True, external=None, stdout=None, stderr=subprocess.STDOUT, interrupt_timeout=0.3, terminate_timeout=0.2)

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Executes a command as a list of strings. If the command fails, the session is stopped by raising an exception.

```APIDOC
## session.run

### Description
Executes a command within the Nox session. Commands must be provided as a list of strings.

### Parameters
- **args** (str | PathLike[str]) - Required - The command and its arguments as separate strings.
- **env** (Mapping[str, str | None]) - Optional - Environment variables to expose to the command.
- **include_outer_env** (bool) - Optional - Whether to include environment variables from the invocation environment. Default: True.
- **silent** (bool) - Optional - If True, captures and returns command output instead of printing it. Default: False.
- **success_codes** (Iterable[int]) - Optional - List of return codes to treat as success. Default: [0].
- **external** (ExternalType) - Optional - If True, suppresses warnings for programs not in the virtualenv.
- **interrupt_timeout** (float) - Optional - Seconds to wait after interrupt before sending terminate signal. Default: 0.3.
- **terminate_timeout** (float) - Optional - Seconds to wait after terminate before sending kill signal. Default: 0.2.
- **stdout** (int | IO[str]) - Optional - Redirect standard output to a file or descriptor.
- **stderr** (int | IO[str]) - Optional - Redirect standard error to a file or descriptor.

### Returns
- **str | bool | None** - Returns the command output if silent=True, otherwise returns None.
```

--------------------------------

### Use current PATH python

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Run a session using the python interpreter currently available in the PATH.

```console
nox --force-python python -s lint
```

```console
NOXFORCEPYTHON=python NOXSESSION=lint nox
```

--------------------------------

### Stop on first error

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Abort session execution immediately upon the first failure.

```default
nox --stop-on-first-error
```

--------------------------------

### Configure default venv backend via environment variable

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Set the default virtual environment backend using the NOX_DEFAULT_VENV_BACKEND environment variable.

```bash
NOX_DEFAULT_VENV_BACKEND=conda
```

--------------------------------

### Run Nox Linting

Source: https://github.com/wntrblm/nox/blob/main/CONTRIBUTING.md

Execute the linting session to check for code style and formatting errors.

```bash
nox --session lint
```

--------------------------------

### Specify Sessions to Run

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Filter sessions using CLI flags or environment variables.

```console
nox --session tests
nox -s lint tests
nox -e lint
```

```console
NOXSESSION=tests nox
NOXSESSION=lint nox
NOXSESSION=lint,tests nox
```

--------------------------------

### View parametrized session IDs

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Run the list command to verify the custom IDs assigned to sessions.

```console
* tests(old)
* tests(new)
```

--------------------------------

### Configure default sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Set a default list of sessions to run when no arguments are provided.

```python
import nox

nox.options.sessions = ["lint", "test"]
```

--------------------------------

### Run Nox sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/index.md

Command to execute all defined sessions.

```bash
nox
```

--------------------------------

### Assign tags to parametrized sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Demonstrates two equivalent ways to assign tags to parametrized sessions using list-based mapping or the nox.param helper.

```python
@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):
    ...
```

```python
@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):
    ...
```

--------------------------------

### Parametrize session output

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Console output showing the creation of distinct sessions based on parametrization.

```console
$ nox
nox > Running session tests(django='1.9')
nox > python -m pip install django==1.9
...
nox > Running session tests(django='2.0')
nox > python -m pip install django==2.0
```

--------------------------------

### Run linting and tests

Source: https://github.com/wntrblm/nox/blob/main/docs/CONTRIBUTING.md

Execute specific Nox sessions to verify code quality and test against various Python environments.

```bash
nox --session lint
```

```bash
nox --session tests-3.12
nox --session conda_tests
nox --session mamba_tests
nox --session micromamba_tests
```

--------------------------------

### Define a PEP 723 script

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

A sample Python script containing metadata for dependencies as defined by PEP 723.

```python
# /// script
# requires-python = ">=3.11"
# dependencies = [
#   "requests<3",
#   "rich",
# ]
# ///

import requests
from rich.pretty import pprint

resp = requests.get("https://peps.python.org/api/peps.json")
data = resp.json()
pprint([(k, v["title"]) for k, v in data.items()][:10])
```

--------------------------------

### List Nox sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

View the expanded sessions generated by multi-version configurations.

```console
Sessions defined in noxfile.py:

* test-3.10
* test-3.11
* test-3.12
```

--------------------------------

### Load configuration from a script file

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

The load_toml function supports loading configurations from both TOML files and PEP 723 script blocks.

```python
@nox.session
def myscript(session):
    myscript_options = nox.project.load_toml("myscript.py")
    session.install(*myscript_options["dependencies"])
```

--------------------------------

### Session.create_tmp

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Creates and returns a temporary directory.

```APIDOC
## Session.create_tmp()

### Description
Creates a new temporary directory and returns its path as a string.
```

--------------------------------

### Enable Bash Autocompletion

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Add this command to your bash configuration file to enable autocompletion.

```console
eval "$(register-python-argcomplete nox)"
```

--------------------------------

### Run all sessions in parallel

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Enable parallel execution globally for all sessions.

```default
nox --parallel auto --allow-parallel
```

--------------------------------

### Session.error

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Immediately aborts the session.

```APIDOC
## Session.error(*args)

### Description
Aborts the current session and optionally logs an error message.
```

--------------------------------

### Run commands with arguments

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Pass additional arguments to the command being executed.

```python
@nox.session
def tests(session):
    session.install("pytest")
    session.run("pytest", "-v", "tests")
```

--------------------------------

### Configure Python interpreter downloads

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Control automatic downloading of Python interpreters via uv or python-build-standalone.

```console
nox --download-python auto    # Download if interpreter not found (default)
nox --download-python never   # Never download interpreters
nox --download-python always  # Always download interpreters
```

--------------------------------

### Configure virtualenv directory in Noxfile

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Sets a custom directory for storing virtualenvs, avoiding the need to pass the argument via the command line.

```python
import nox

nox.options.envdir = ".cache"

@nox.session
def tests(session):
    ...
```

--------------------------------

### Run specific parametrized sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Target a specific parameter combination by appending the argument to the session name in the CLI.

```console
nox --session "tests(django='1.9')"
nox --session "tests(django='2.0')"
```

--------------------------------

### Invoke Nox via CLI

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Standard ways to execute Nox from the terminal.

```console
nox
```

```console
python3 -m nox
```

--------------------------------

### skip

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Immediately terminates the current session and optionally logs a warning.

```APIDOC
## skip(*args)

### Description
Immediately skips the session and optionally logs a warning.
```

--------------------------------

### Enable Zsh Autocompletion

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Requires bashcompinit to be enabled before registering the completion command.

```console
# To activate completions for zsh you need to have
# bashcompinit enabled in zsh:
autoload -U bashcompinit
bashcompinit

# Afterwards you can enable completion for Nox:
eval "$(register-python-argcomplete nox)"
```

--------------------------------

### List stacked session results

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

The resulting sessions generated by stacking multiple parametrize decorators.

```console
* tests(database='postgres', django='1.9')
* tests(database='mysql', django='1.9')
* tests(database='postgres', django='2.0')
* tests(database='mysql', django='2.0')
```

--------------------------------

### Handle cleanup with try-finally

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Use a try-finally block to ensure cleanup tasks run even if the primary command fails.

```python
try:
    session.run("coverage", "run", "-m", "pytest")
finally:
    # Display coverage report even when tests fail.
    session.run("coverage", "report")
```

--------------------------------

### Define Nox sessions

Source: https://github.com/wntrblm/nox/blob/main/README.md

Use a noxfile.py to define test and lint sessions using the @nox.session decorator.

```python
import nox


@nox.session
def tests(session: nox.Session) -> None:
    session.install("pytest")
    session.run("pytest")

@nox.session
def lint(session: nox.Session) -> None:
    session.install("flake8")
    session.run("flake8", "--import-order-style", "google")
```

--------------------------------

### Run commands with environment variables

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Execute a command while setting specific environment variables.

```python
@nox.session
def tests(session):
    session.install("pytest")
    session.run(
        "pytest",
        env={
            "FLASK_DEBUG": "1"
        }
    )
```

--------------------------------

### Add a session description

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Include a docstring in the session function to provide a description visible when listing sessions.

```python
import nox

@nox.session
def tests(session):
    """Run the test suite."""
    session.run('pytest')
```

--------------------------------

### Change working directory with session.chdir

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Use as a context manager to temporarily change the working directory and automatically restore it afterward.

```default
with session.chdir("somewhere/deep/in/monorepo"):
    # Runs in "/somewhere/deep/in/monorepo"
    session.run("pytest")

# Runs in original working directory
session.run("flake8")
```

--------------------------------

### Specify custom configuration file

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Overrides the default noxfile.py filename using command line arguments.

```console
nox --noxfile something.py
nox -f something.py
```

--------------------------------

### Configure environment variables

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Use the env parameter to pass specific environment variables to the command.

```python
session.run(
    'bash', '-c', 'echo $SOME_ENV',
    env={'SOME_ENV': 'Hello'})
```

--------------------------------

### Add Nox badge to documentation

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Use these snippets to display the official Nox badge in your project's README file.

```markdown
[![Nox](https://img.shields.io/badge/%F0%9F%A6%8A-Nox-D85E00.svg)](https://github.com/wntrblm/nox)
```

```rst
.. image:: https://img.shields.io/badge/%F0%9F%A6%8A-Nox-D85E00.svg
   :alt: Nox
   :target: https://github.com/wntrblm/nox
```

--------------------------------

### nox.project.load_toml

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Loads a TOML file or a Python script containing a PEP 723 metadata block into a dictionary.

```APIDOC
## nox.project.load_toml(filename: os.PathLike[str] | str = 'pyproject.toml', *, missing_ok: bool = False) -> dict[str, Any]

### Description
Parses a TOML file or extracts metadata from a PEP 723 script block. Supports .toml, .py, or files without extensions.

### Parameters
- **filename** (os.PathLike[str] | str) - Optional - Path to the file. Defaults to 'pyproject.toml'.
- **missing_ok** (bool) - Optional - If True, returns an empty dict instead of raising an error when a script block is missing.

### Returns
- **dict[str, Any]** - The parsed configuration data.
```

--------------------------------

### Run Nox in the terminal

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Execute the nox command in your project directory to run defined sessions.

```console
$ nox
nox > Running session lint
nox > Creating virtualenv using python3.14 in .nox/lint
nox > pip install flake8
nox > flake8 example.py
nox > Session lint was successful.
```

--------------------------------

### Parametrize Python interpreters

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Select Python versions using either the parametrize decorator or the session decorator argument.

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

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

--------------------------------

### Configure Nox in GitHub Actions

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

YAML configuration for the wntrblm/nox GitHub Action, supporting both default and custom Python version specifications.

```yaml
# setup nox with the default set of CPython versions i.e.
# python-versions: "3.10, 3.11, 3.12, 3.13, 3.14"
# Any Nox tag will work here
- uses: wntrblm/nox@2026.07.11

# setup nox only for a given list of python versions
# Limitations:
# - Version specifiers shall be supported by actions/setup-python
# - There can only be one "major.minor" per interpreter i.e. "3.12.0, 3.12.1" is invalid
# Any Nox tag will work here
- uses: wntrblm/nox@2026.07.11
  with:
      python-versions: "3.10, 3.14, pypy-3.11"
```

--------------------------------

### Enable Tcsh Autocompletion

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Register the completion command specifically for the tcsh shell.

```console
eval `register-python-argcomplete --shell tcsh nox`
```

--------------------------------

### Queue sessions with session.notify

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Use session.notify to trigger another session after the current one completes.

```python
@nox.session
def tests(session):
    session.install("pytest")
    session.run("pytest")
    # Here we queue up the test coverage session to run next
    session.notify("coverage")

@nox.session
def coverage(session):
    session.install("coverage")
    session.run("coverage")
```

--------------------------------

### Generate GitHub Actions matrix dynamically

Source: https://github.com/wntrblm/nox/blob/main/docs/cookbook.md

Uses the Nox JSON output to dynamically configure a GitHub Actions matrix. Requires the jq utility to be available in the runner environment.

```yaml
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 }}"
```

--------------------------------

### Pass arguments to a session

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Use session.posargs to access command-line arguments passed to the session. If no arguments are provided, it defaults to a predefined list of files.

```python
@nox.session
def test(session):
    session.install('pytest')

    if session.posargs:
        test_files = session.posargs
    else:
        test_files = ['test_a.py', 'test_b.py']

    session.run('pytest', *test_files)
```

--------------------------------

### nox.parametrize(arg_names, arg_values_list, ids=None, tags=None)

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Parametrizes a session function by adding new invocations based on the provided argument values. Each combination of arguments results in a separate session during discovery.

```APIDOC
## nox.parametrize

### Description
Parametrize a session. Add new invocations to the underlying session function using the list of `arg_values_list` for the given `arg_names`. Parametrization is performed during session discovery and each invocation appears as a separate session to Nox.

### Parameters
- **arg_names** (Sequence[str]) - Required - A list of argument names.
- **arg_values_list** (Sequence[Union[Any, Tuple]]) - Required - The list of argument values determines how often a session is invoked with different argument values.
- **ids** (Sequence[str]) - Optional - Optional sequence of test IDs to use for the parametrized arguments.
- **tags** (Iterable[Sequence[str]]) - Optional - Optional iterable of tags to associate with the parametrized arguments.

### Usage Example
```python
@nox.session
@nox.parametrize('django', ['1.9', '2.0'])
def tests(session, django):
    session.install(f'django=={django}')
    session.run('pytest')
```
```

--------------------------------

### Run a specific Nox session

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Execute a session by its custom name using the --session flag.

```console
$ nox --session "custom-name"
Hello!
```

--------------------------------

### Define default sessions in Noxfile

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Specifies a list of sessions to run by default, overriding the default argument provided to sessions.

```python
import nox

nox.options.sessions = ["lint", "tests-3.14"]

...
```

--------------------------------

### Stack parameterizations with custom IDs

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

IDs are combined when multiple parameters are stacked.

```python
@nox.session
@nox.parametrize(
    'django',
    ['1.9', '2.0'],
    ids=["old", "new"])
@nox.parametrize(
    'database',
    ['postgres', 'mysql'],
    ids=["psql", "mysql"])
def tests(session, django, database):
    ...
```

--------------------------------

### Force Nox virtualenv backend via CLI

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Forces a specific backend for all sessions during the current execution. Command-line arguments override Noxfile configurations.

```console
nox -fb conda
nox --force-venv-backend conda
```

--------------------------------

### View expanded session list

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Nox creates a separate session for each interpreter defined in the list.

```python
@nox.session(python=['3.10', '3.11', '3.12', '3.13', '3.14'])
def tests(session):
    pass
```

```console
* tests-3.10
* tests-3.11
* tests-3.12
* tests-3.13
* tests-3.14
```

--------------------------------

### notify

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Queues a session to run after the current session completes.

```APIDOC
## notify(target, posargs=None)

### Description
Place the given session at the end of the queue. This method is idempotent.

### Parameters
- **target** (str | SessionRunner) - Required - The session name to notify.
- **posargs** (Iterable[str]) - Optional - Positional arguments for the queued session.

### Raises
- **ValueError** - If called under --no-dependencies.
```

--------------------------------

### Define script dependencies for Nox

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Include this comment block at the top of the noxfile to specify dependencies for the script runner.

```python
# /// script
# dependencies = ["nox"]
# ///
```

--------------------------------

### Run extra Python versions

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Specify additional Python versions to run alongside those defined in the Noxfile.

```console
nox --extra-pythons 3.12 3.13 3.14
```

```console
NOXEXTRAPYTHON=3.12,3.13,3.14 nox
```

--------------------------------

### Add tags to Nox sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Apply tags to sessions to group them for execution via the command line.

```python
@nox.session(tags=["style", "fix"])
def black(session):
    session.install("black")
    session.run("black", "my_package")

@nox.session(tags=["style", "fix"])
def isort(session):
    session.install("isort")
    session.run("isort", "my_package")

@nox.session(tags=["style"])
def flake8(session):
    session.install("flake8")
    session.run("flake8", "my_package")
```

--------------------------------

### List sessions with a filter

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Output showing only the lint session selected when using the --sessions argument.

```console
Sessions defined in noxfile.py:

- test
* lint
- docs

sessions marked with * are selected,
sessions marked with - are skipped.
```

--------------------------------

### Parametrize a Nox session

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Define a session with multiple parameter sets using the @nox.parametrize decorator.

```python
@nox.parametrize('django', ['1.9', '2.0'])
def tests(session, django):
    ...
```

--------------------------------

### View stacked session IDs

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

The resulting session list after stacking parameters with IDs.

```console
* tests(psql, old)
* tests(mysql, old)
* tests(psql, new)
* tests(mysql, new)
```

--------------------------------

### Session.chdir

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Changes the current working directory. Can be used as a context manager to automatically restore the previous directory.

```APIDOC
## Session.chdir(dir: str | PathLike[str])

### Description
Changes the current working directory. Can be used as a context manager to automatically restore the working directory.

### Parameters
- **dir** (str | PathLike[str]) - Required - The directory to change to.
```

--------------------------------

### Require parameterized sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Use {python} to reference the current Python version in required session names.

```python
@nox.session(python=["3.10", "3.13"])
def tests(session):
    session.install("pytest")
    session.run("pytest")

@nox.session(python=["3.10", "3.13"], requires=["tests-{python}"])
def coverage(session):
    session.install("coverage")
    session.run("coverage")
```

--------------------------------

### Force Python interpreter usage

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Use the --force-python shorthand to replace the interpreter for a session.

```console
nox --force-python 3.11 -s lint
```

```console
NOXFORCEPYTHON=3.11 NOXSESSION=lint nox
```

--------------------------------

### Run sessions in parallel

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Execute independent sessions concurrently using CPU-based or fixed-count limits.

```default
nox --parallel auto   # one session per CPU
nox -j 4              # at most four sessions at once
```

--------------------------------

### Change virtualenv directory

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Use the --envdir flag to specify a custom directory for storing virtual environments instead of the default ./.nox.

```console
nox --envdir /tmp/envs
```

--------------------------------

### Define multiple sessions in a Noxfile

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

A basic Noxfile structure containing three distinct sessions.

```python
import nox

@nox.session
def test(session):
    ...

@nox.session
def lint(session):
    ...

@nox.session
def docs(session):
    ...
```

--------------------------------

### Define custom IDs for parametrized sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Use the ids argument or nox.param to provide readable identifiers for parametrized sessions.

```python
@nox.session
@nox.parametrize('django',
    ['1.9', '2.0'],
    ids=['old', 'new'])
def tests(session, django):
    ...
```

```python
@nox.session
@nox.parametrize('django', [
    nox.param('1.9', id='old'),
    nox.param('2.0', id='new'),
])
def tests(session, django):
    ...
```

--------------------------------

### Configure conda virtual environment

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Set the venv_backend to conda to run sessions within a conda environment.

```python
@nox.session(venv_backend="conda")
def test(session):
    ...
```

--------------------------------

### Run Nox without virtualenvs

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Executes selected sessions using the current Python interpreter instead of creating a virtualenv.

```console
nox --no-venv
```

--------------------------------

### Filter Sessions by Keywords and Tags

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Use pytest-style keyword expressions or tags to select specific sessions.

```console
nox -k "not lint"
nox -k "tests and not lint"
nox -k "not my_tag"
nox -t "my_tag" "my_other_tag"
```

--------------------------------

### Generate Machine-Readable Report

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.md

Output session status to a JSON file.

```console
nox --report status.json
```

--------------------------------

### Configure session for specific Python versions

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.md

Use the python parameter in @nox.session to target one or more Python interpreters.

```python
@nox.session(python="3.12")
def test(session):
    ...
```

```python
@nox.session(python=["3.10", "3.11", "3.12"])
def test(session):
    ...
```

--------------------------------

### warn

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Outputs a warning message during the session execution.

```APIDOC
## warn(*args, **kwargs)

### Description
Outputs a warning during the session.
```

--------------------------------

### Capture command output

Source: https://github.com/wntrblm/nox/blob/main/docs/config.md

Set silent=True to capture and return the command output instead of displaying it.

```python
out = session.run(
    "git", "rev-parse", "--short", "HEAD",
    external=True, silent=True
)

print("Current Git commit is", out.strip())
```

--------------------------------

### Run Specific Nox Test Sessions

Source: https://github.com/wntrblm/nox/blob/main/CONTRIBUTING.md

Execute tests for specific Python versions or environment managers.

```bash
nox --session tests-3.12
nox --session conda_tests
nox --session mamba_tests
nox --session micromamba_tests
```
Tokens:
Raw