Nox

https://nox.thea.codes/en/stable/
Admin
Nox is a command-line tool for automating testing in multiple Python environments, configured via a...
Tokens:62,220
Snippets:471
Trust Score:7.5
Update:1 year ago
Show doc for...
Tokens:
Raw
### Running External Commands and Installations

Source: https://nox.thea.codes/en/stable/_sources/tutorial.rst

Demonstrates how to execute external build commands and install packages using Nox sessions. Includes examples for building, installing, and running scripts.

```python
session.run(
    "cmake",
    "--build", build_dir,
    "--config", "Debug",
    "--target", "install",
    external=True,
)
```

```python
session.install(".")
```

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

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

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

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

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

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

### Nox Session Installation Examples

Source: https://nox.thea.codes/en/stable/config

Demonstrates how to install packages using the Nox session's `install` method. This includes installing a single package, multiple packages, packages with specific versions, and packages from a requirements file. It also shows how to install the current project in editable mode.

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

```python
session.install('pytest')
```

```python
session.install('requests', 'mock')
```

```python
session.install('requests[security]==2.9.1')
```

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

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

```python
session.install('.')
```

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

### Instant Dev Environment with Nox

Source: https://nox.thea.codes/en/stable/_sources/cookbook.rst

Sets up a Python development environment by creating a virtual environment and installing project dependencies. This session is useful for beginners to automate environment setup.

```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 it's dev dependencies, this ensures it's installed in the right way
    session.run(".venv/bin/pip", "install", "-e", ".[dev]", external=True)
```

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

### Setup Nox with GitHub Actions

Source: https://nox.thea.codes/en/stable/_sources/tutorial.rst

Configures Nox in GitHub Actions to use all active CPython and PyPY versions provided by the environment. This example uses a specific Nox tag.

```yaml
# setup nox with all active CPython and PyPY versions provided by
# the GitHub Actions environment i.e.
# python-versions: "3.8, 3.9, 3.10, 3.11, 3.12, pypy-3.8, pypy-3.9, pypy-3.10"
# Any Nox tag will work here
- uses: wntrblm/nox@2024.04.15
```

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

### Install Only Execution Example

Source: https://nox.thea.codes/en/stable/_sources/usage.rst

Demonstrates the output when Nox is run with the `--install-only` flag, showing that installation commands are executed but the `run` command is skipped.

```console
nox --install-only

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.
```

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

### Basic Nox Session

Source: https://nox.thea.codes/en/stable/_sources/config.rst

Defines a basic Nox session that installs Nox and runs a command. This is a fundamental example for setting up a Nox environment.

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

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

### Install Project Package

Source: https://nox.thea.codes/en/stable/tutorial

Installs the current Python project package into the Nox session environment. This is equivalent to running `pip install .`.

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

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

### Install from Requirements File

Source: https://nox.thea.codes/en/stable/tutorial

Installs dependencies from a requirements file (e.g., `requirements.txt`) into the Nox session environment. This is equivalent to running `pip install -r requirements.txt`.

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

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

### Install Nox using pip

Source: https://nox.thea.codes/en/stable/tutorial

Installs Nox using pip, with an option for user site installation to avoid global conflicts.

```shell
python3 -m pip install nox

```

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

```

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

### Fix Pip Installation Example

Source: https://nox.thea.codes/en/stable/CHANGELOG

Corrects the example installation call for pip in the documentation, ensuring users have accurate guidance for installing packages.

```bash
# Corrected pip installation example
# pip install nox
```

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

### Install and Upgrade Nox

Source: https://nox.thea.codes/en/stable/_sources/CONTRIBUTING.md

Installs or upgrades Nox to the latest pre-release version. It's recommended to start with a known-good installation.

```shell
pip install --pre --upgrade nox
```

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

### Install dependencies from requirements.txt in a Nox session

Source: https://nox.thea.codes/en/stable/_sources/tutorial.rst

Installs all dependencies listed in a `requirements.txt` file into the Nox session's virtual environment, equivalent to `pip install -r requirements.txt`.

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

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

### Install and Run PEP 723 Script Helper

Source: https://nox.thea.codes/en/stable/tutorial

A convenience function to install dependencies from and run a PEP 723 compliant script.

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

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

### Install Nox using pipx

Source: https://nox.thea.codes/en/stable/tutorial

Installs Nox as a standalone command-line tool using pipx.

```shell
pipx install nox

```

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

### Install Nox using pip (user site)

Source: https://nox.thea.codes/en/stable/_sources/tutorial.rst

Installs Nox to the user site directory, preventing interference with the system-wide Python installation.

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

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

### Install Nox using pip

Source: https://nox.thea.codes/en/stable/_sources/tutorial.rst

Installs Nox globally using pip. It's recommended to use the user site to avoid conflicts with the global Python installation.

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

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

### Install Nox

Source: https://nox.thea.codes/en/stable/_sources/index.rst

Instructions for installing Nox using pipx or pip.

```bash
pipx install nox
```

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

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

### Install Multiple Packages

Source: https://nox.thea.codes/en/stable/tutorial

Installs one or more Python packages into the Nox session environment. This is equivalent to running `pip install package1 package2`.

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

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

### Install the project itself in a Nox session

Source: https://nox.thea.codes/en/stable/_sources/tutorial.rst

Installs the current Python project into the Nox session's virtual environment, typically used for testing the package itself. This is the same as `pip install .`.

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

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

### Install Package in Editable Mode

Source: https://nox.thea.codes/en/stable/config

Installs the current project in editable mode using session.install. This is a common practice for development setups.

```python
session.install('-e', '.')

```

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

### Basic Noxfile for linting

Source: https://nox.thea.codes/en/stable/_sources/tutorial.rst

A simple Noxfile defining a 'lint' session that installs flake8 and runs it against 'example.py'. This demonstrates the basic structure of a Nox session.

```python
import nox

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

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

### Install Only Mode

Source: https://nox.thea.codes/en/stable/_sources/usage.rst

Instructs Nox to only execute installation commands (`session.install`) and skip all other commands (`session.run`). This is useful for preparing environments or replicating setups without running tests or other processes.

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

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

### Loading Dependencies with nox.project.load_toml

Source: https://nox.thea.codes/en/stable/_sources/tutorial.rst

Shows how to load dependencies from a pyproject.toml file or a PEP 723 script using nox.project.load_toml. This is useful for preparing environments without full installation.

```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])
```

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

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

### Install Nox using pipx

Source: https://nox.thea.codes/en/stable/_sources/tutorial.rst

Installs Nox as a standalone command-line application using pipx, ensuring it doesn't interfere with other Python projects.

```console
pipx install nox
```

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

### Instant Dev Environment with Nox

Source: https://nox.thea.codes/en/stable/cookbook

Sets up a Python development environment using Nox. It installs virtualenv, creates a .venv directory, and installs the project with its development dependencies.

```python
import nox

@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 it's dev dependencies, this ensures it's installed in the right way
    session.run(".venv/bin/pip", "install", "-e", ".[dev]", external=True)

```

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

### Install Nox with pip

Source: https://nox.thea.codes/en/stable/index

Installs the Nox command-line tool using pip, suitable for global Python installations.

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

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

### Installing Packages with Conda

Source: https://nox.thea.codes/en/stable/_sources/tutorial.rst

Demonstrates how to install packages into a conda environment using `session.conda_install`, specifying channels for consistency.

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

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

### Install multiple packages in a Nox session

Source: https://nox.thea.codes/en/stable/_sources/tutorial.rst

Installs multiple Python packages into the Nox session's virtual environment, similar to `pip install package1 package2`.

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

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

### Nox Session List Example

Source: https://nox.thea.codes/en/stable/_sources/config.rst

Demonstrates the output of the 'nox --list' command, showing available sessions with their respective parameters.

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

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

### session.install_and_run_script

Source: https://nox.thea.codes/en/stable/_sources/CHANGELOG.md

Introduces a new method `session.install_and_run_script` for executing scripts after installation. This simplifies workflows where a script needs to be run as part of the session setup or execution.

```python
# Example usage (conceptual):
# @nox.session(python='3.11')
# def run_setup_script(session):
#     session.install('some-package')
#     session.install_and_run_script('setup.py', 'install')

```

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

### Parametrizing Sessions with Nox

Source: https://nox.thea.codes/en/stable/_sources/tutorial.rst

Introduces the `@nox.parametrize` decorator for running sessions with different arguments, using an example of testing against different Django versions.

```python
@nox.session
@nox.parametrize("django", ["4.0", "4.1"])
def tests_with_django(session, django):
    session.install(f"Django=={django}")
    session.run("pytest")

```

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

### Noxfile with Default Sessions

Source: https://nox.thea.codes/en/stable/_sources/tutorial.rst

Example of configuring Nox to run a default set of sessions when no specific sessions are provided.

```python
import nox

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

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

### Install Nox with pipx

Source: https://nox.thea.codes/en/stable/index

Installs the Nox command-line tool using pipx, a tool for installing and running Python applications in isolated environments.

```bash
pipx install nox
```

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

### Load Dependencies from PEP 723 Script

Source: https://nox.thea.codes/en/stable/tutorial

Loads dependencies specified in a PEP 723 compliant script (e.g., `peps.py`) and installs them. It then runs the script.

```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])
```

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

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

### Running Coverage Session

Source: https://nox.thea.codes/en/stable/_sources/tutorial.rst

Defines a Nox session named 'coverage' that installs the 'coverage' package and then runs the 'coverage' command.

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

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

### Basic Noxfile Session

Source: https://nox.thea.codes/en/stable/tutorial

Defines a simple Nox session to install and run flake8 against a Python file.

```python
import nox

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

```

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

### Install with External Build Dependencies

Source: https://nox.thea.codes/en/stable/tutorial

Installs the Python package while ensuring external build dependencies (like CMake) are available and executed. This is useful for packages with C/C++ 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(".")
    ...
```

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

### Parametrized Session Example

Source: https://nox.thea.codes/en/stable/_sources/tutorial.rst

Demonstrates how to use `@nox.parametrize` to create multiple sessions based on different argument values, similar to pytest's parametrize.

```python
@nox.parametrize("django", ["1.9", "2.0"])
def test(session, django):
    session.install(f"django=={django}")
    session.run("pytest")
```

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

### Define Multiple Nox Sessions

Source: https://nox.thea.codes/en/stable/tutorial

Demonstrates how to define multiple distinct sessions within a Noxfile. Each session is decorated with `@nox.session` and can contain its own installation and execution logic.

```python
import nox

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

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

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

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

### Session Tags Example

Source: https://nox.thea.codes/en/stable/_sources/tutorial.rst

Illustrates how to add tags to Nox sessions for organization and selective execution. Multiple sessions can share the same tags.

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

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

### UV Backend Pip Installation Note

Source: https://nox.thea.codes/en/stable/usage

A note regarding the 'uv' backend, which does not install 'pip' by default. 'pip' can be installed manually using `session.install('pip')`.

```python
session.install("pip")
```

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

### Install Packages with Conda

Source: https://nox.thea.codes/en/stable/tutorial

Installs packages into a conda environment using `session.conda_install()`. It's recommended to specify channels for consistency and to use the `--no-deps` option when installing pip packages to avoid conflicts.

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

```

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

### Run Python Tool

Source: https://nox.thea.codes/en/stable/tutorial

Installs a Python tool (e.g., pytest) and then runs it within the session's virtual environment.

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

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

### Install Nox with Tox Conversion Support

Source: https://nox.thea.codes/en/stable/_sources/usage.rst

Installs Nox with the necessary extras to enable experimental conversion of tox.ini files to noxfile.py. This simplifies migrating from tox to Nox.

```console
pip install --upgrade nox[tox_to_nox]
```

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

### Basic Noxfile Configuration

Source: https://nox.thea.codes/en/stable/index

A simple noxfile.py demonstrating how to define sessions for running tests and linting. It installs dependencies and runs commands within isolated virtual environments.

```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')
```

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

### Run Command with Arguments

Source: https://nox.thea.codes/en/stable/tutorial

Runs a command with additional arguments passed to it. This example runs pytest with verbose output and specifies a test directory.

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

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

### Setup Nox with GitHub Actions (specific versions)

Source: https://nox.thea.codes/en/stable/_sources/tutorial.rst

Configures Nox in GitHub Actions for a specific list of Python versions. Note that version specifiers must be supported by actions/setup-python, and only one major.minor version per interpreter is allowed.

```yaml
# 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@2024.04.15
  with:
      python-versions: "2.7, 3.5, 3.11, pypy-3.9"
```

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

### Noxfile Parametrized Session Example

Source: https://nox.thea.codes/en/stable/usage

An example of how to define a parametrized session in a Noxfile using `@nox.parametrize`.

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

```

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

### Installing Pip Packages into Conda Environment

Source: https://nox.thea.codes/en/stable/_sources/tutorial.rst

Shows the recommended way to install pip packages into a conda environment using the `--no-deps` option to avoid conflicts.

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

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

### Running Nox with Positional Arguments

Source: https://nox.thea.codes/en/stable/_sources/config.rst

Examples of how to run Nox sessions from the command line, both with and without positional arguments to control test execution.

```console
nox

# Output:
# pytest test_a.py test_b.py
```

```console
nox -- test_c.py

# Output:
# pytest test_c.py
```

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

### Selecting Nox Sessions

Source: https://nox.thea.codes/en/stable/_sources/tutorial.rst

Illustrates how to select specific Nox sessions to run using the --sessions argument and how to view available sessions with --list. Also shows how to set default sessions in the Noxfile.

```console
nox --list
```

```console
nox --list --sessions lint
```

```console
nox --sessions lint
```

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

### Install Dependencies Only (--install-only)

Source: https://nox.thea.codes/en/stable/CHANGELOG

Adds the `--install-only` flag, which instructs Nox to install dependencies for the selected sessions but not to execute any commands. This is useful for setting up environments without running tasks.

```bash
# Install dependencies for the 'lint' session without running it
# nox --install-only -s lint
```

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

### Automated Release Process with Nox

Source: https://nox.thea.codes/en/stable/_sources/cookbook.rst

Automates the release process by creating and pushing a new tag using bump2version. This session requires bump2version to be installed and configured.

```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 bump2version with the posarg setting the version.

    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("bump2version")

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

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

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

### Documentation on Using Docker with Nox

Source: https://nox.thea.codes/en/stable/CHANGELOG

Adds documentation explaining how to use Docker to run Nox sessions. This guides users on containerizing their Nox workflows.

```markdown
## Running Nox with Docker

To run Nox sessions within a Docker container, you can create a Dockerfile that installs Nox and your project's dependencies. Then, you can mount your project directory and execute Nox commands inside the container.

**Dockerfile Example:**

```dockerfile
FROM python:3.9-slim

RUN pip install nox

WORKDIR /app

CMD ["nox"]
```

**Running:**

```bash
docker build -t nox-runner .
docker run --rm -v $(pwd):/app nox-runner -s <session_name>
```
```

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

### Install Only Flag

Source: https://nox.thea.codes/en/stable/_sources/CHANGELOG.md

Demonstrates the `--install-only` flag, which allows Nox to install session dependencies without executing any session commands. This is useful for setting up environments.

```python
from nox import session

@session
def setup_environment(session):
    """Installs dependencies for the environment."""
    session.install('requests', 'pytest')

# Run with: nox --install-only

```

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

### Noxfile Configuration Example

Source: https://nox.thea.codes/en/stable/_sources/config.rst

Demonstrates how to modify Nox's behavior directly within the Noxfile using 'nox.options'.

```python
import nox

nox.options.envdir = ".cache"

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

```python
import nox

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

...
```

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

### Run Command with Environment Variables

Source: https://nox.thea.codes/en/stable/tutorial

Runs a command while setting specific environment variables for the execution context. This example sets FLASK_DEBUG to '1'.

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

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

### Run Nox Sessions

Source: https://nox.thea.codes/en/stable/index

Command to execute all defined sessions in the noxfile.py. Nox automatically creates virtual environments, installs dependencies, and runs the specified commands for each session.

```bash
nox
```

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

### Nox Dependency Updates

Source: https://nox.thea.codes/en/stable/_sources/CHANGELOG.md

Nox has updated its dependency ranges, including for the 'colorlog' package. Additionally, the installation command in the contributing guide has been updated.

```python
# Update colorlog dependency range.
# Update installation command in contributing.
```

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

### Run Session with Custom Name

Source: https://nox.thea.codes/en/stable/_sources/config.rst

Example of how to run a Nox session using its custom name.

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

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

### Nox Session Installation with Pathlib

Source: https://nox.thea.codes/en/stable/_sources/CHANGELOG.md

The `session.install` method in Nox can now accept `pathlib.Path` objects for specifying requirements files or packages, aligning with modern Python practices.

```python
from pathlib import Path

def install_requirements(session):
    session.install("-r", Path("requirements-dev.txt"))
```

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

### Stacked Parametrization for Combinations

Source: https://nox.thea.codes/en/stable/config

Shows how to stack multiple `nox.parametrize` decorators to create sessions that are combinations of different arguments. This example parametrizes both Django version and database type.

```python
@nox.session
@nox.parametrize('django', ['1.9', '2.0'])
@nox.parametrize('database', ['postgres', 'mysql'])
def tests(session, django, database):
    # ... session logic ...
    pass

```

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

### Nox Documentation Updates (2025.05.01)

Source: https://nox.thea.codes/en/stable/CHANGELOG

Details documentation updates for the Nox 2025.05.01 release. Includes fixing a typo in the changelog, updating the uv recipe, correcting a parametrized session tagging example, and noting uv's support for `pip install .` reinstallation.

```python
# Fix a typo in the changelog by @gschaffner in https://github.com/wntrblm/nox/pull/936
# Update uv recipe by @henryiii in https://github.com/wntrblm/nox/pull/933
# Fix parametrized session tagging example by @living180 in https://github.com/wntrblm/nox/pull/942
# uv now supports `pip install .` reinstallation by @henryiii in https://github.com/wntrblm/nox/pull/947
```

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

### Nox Session API Documentation

Source: https://nox.thea.codes/en/stable/config

Provides detailed documentation for various Nox session methods, including their purpose, parameters, return values, and usage examples. This covers methods for creating temporary directories, debugging, managing environment variables, and handling errors.

```APIDOC
create_tmp() → str
    Create, and return, a temporary directory.

debug(_* args:Any_, _** kwargs:Any_) → None
    Outputs a debug-level message during the session.

env _: dict[str,str|None]
    A dictionary of environment variables to pass into all commands.

error(_* args:Any_) → NoReturn
    Immediately aborts the session and optionally logs an error.

install(_* args:str_, _env :Mapping[str,str]|None=None_, _include_outer_env :bool=True_, _silent :bool|None=None_, _success_codes :Iterable[int]|None=None_, _log :bool=True_, _external :ExternalType|None=None_, _stdout :int|IO[str]|None=None_, _stderr :int|IO[str]|None=-2_, _interrupt_timeout :float|None=0.3_, _terminate_timeout :float|None=0.2_) → None
    Install invokes [pip](https://pip.readthedocs.org) to install packages inside of the session’s virtualenv.
```

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

### Nox Installation Command

Source: https://nox.thea.codes/en/stable/_sources/CHANGELOG.md

Nox is now published on PyPI under the name 'nox'. The installation command has been updated from `pip install nox-automation` to `pip install nox`. This change is associated with a major release that includes breaking changes, and the older package will not be updated.

```python
# Previous installation command:
# pip install nox-automation

# New installation command:
# pip install nox
```

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

### Using Mamba or Micromamba Backend

Source: https://nox.thea.codes/en/stable/_sources/tutorial.rst

Explains that 'mamba' and 'micromamba' are also valid choices for the `venv_backend` argument, allowing the use of these faster package managers.

```python
@nox.session(venv_backend="mamba")
def test_mamba(session):
    ...

@nox.session(venv_backend="micromamba")
def test_micromamba(session):
    ...

```

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

### Install Only Mode

Source: https://nox.thea.codes/en/stable/usage

Instructs Nox to only execute installation commands within sessions, skipping any 'run' commands. This is useful for preparing environments or testing installation processes.

```shell
nox --install-only
```

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

### Nox UV Backend Integration

Source: https://nox.thea.codes/en/stable/CHANGELOG

This snippet shows how Nox integrates with the UV package installer. It demonstrates handling potential errors when UV is not installed and correctly invoking UV for package installations.

```python
import nox
from nox.sessions import Session

@nox.session
def install_with_uv(session: Session):
    """Installs packages using UV as the backend."""
    session.log("Attempting to install with UV...")
    try:
        # Use 'uv python install' if UV is available and configured
        session.run("uv", "python", "install", ".", "--no-cache", external=True)
        session.log("Installation with UV successful.")
    except nox.exceptions.CommandFailed as e:
        session.log(f"UV installation failed: {e}. Falling back or handling error.")
        # Handle cases where UV might not be installed or fails
        # For example, you might fall back to pip:
        # session.install(".")

@nox.session
def uvx_install(session: Session):
    """Installs packages using 'uvx' command, treating it like 'uv'."""
    session.log("Attempting to install with uvx...")
    try:
        session.run("uvx", "install", ".", external=True)
        session.log("Installation with uvx successful.")
    except nox.exceptions.CommandFailed as e:
        session.log(f"uvx installation failed: {e}. Ensure uvx is installed.")

```

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

### Basic Noxfile Configuration

Source: https://nox.thea.codes/en/stable/_sources/index.rst

A simple noxfile.py demonstrating how to define 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')
```

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

### Install Pip Packages in Conda Environment

Source: https://nox.thea.codes/en/stable/tutorial

Installs pip packages into a conda environment with the `--no-deps` flag to prevent conflicts with conda-managed packages. It's also advised to specify channels for conda installations.

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

```

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

### Nox Session Install Outside Venv

Source: https://nox.thea.codes/en/stable/_sources/CHANGELOG.md

The behavior of `session.install` when run outside a virtual environment has been changed. Previously, it might have installed packages globally or in unexpected locations. Now, it is disabled to ensure installations are confined to the intended virtual environments.

```python
# This call might behave differently or be disallowed depending on Nox version and context
# session.install("pytest")
```

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

### Running Sessions by Tag (Multiple Tags - OR Logic)

Source: https://nox.thea.codes/en/stable/_sources/tutorial.rst

Shows how to run sessions that match any of the specified tags. Nox executes sessions tagged with 'style' OR 'fix'.

```console
nox -t style fix
```

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

### Parametrize Session with Arguments

Source: https://nox.thea.codes/en/stable/tutorial

Uses the `nox.parametrize()` decorator to run a session with different argument values. This allows for testing various configurations, such as different library versions, within a single session definition.

```python
@nox.session
@nox.parametrize("django", ["1.9", "2.0"])
def test(session, django):
    session.install(f"django=={django}")
    session.run("pytest")

```

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

### Conda Package Installation

Source: https://nox.thea.codes/en/stable/config

Installs packages using conda within the session's environment. Supports installing individual packages, multiple packages, packages with specific versions, from channels, and from requirements files. Includes an `auto_offline` option to automatically add the `--offline` flag when no internet connection is detected.

```APIDOC
Session.conda_install(*args: str, auto_offline: bool = True, channel: str|Sequence[str] = '', env: Mapping[str, str]|None = None, include_outer_env: bool = True, silent: bool|None = None, success_codes: Iterable[int]|None = None, log: bool = True, stdout: int|IO[str]|None = None, stderr: int|IO[str]|None = -2, interrupt_timeout: float|None = 0.3, terminate_timeout: float|None = 0.2) -> None
    Install invokes [conda install](https://nox.thea.codes/en/stable/config.html#conda-install) to install packages inside of the session’s environment.
    To install packages directly:
    ```python
    session.conda_install('pandas')
    session.conda_install('numpy', 'scipy')
    session.conda_install('dask==2.1.0', channel='conda-forge')
    ```

    To install packages from a `requirements.txt` file:
    ```python
    session.conda_install('--file', 'requirements.txt')
    session.conda_install('--file', 'requirements-dev.txt')
    ```

    By default this method will detect when internet connection is not available and will add the –offline flag automatically in that case. To disable this behaviour, set auto_offline=False.
    To install the current package without clobbering conda-installed dependencies:
    ```python
    session.install('.', '--no-deps')
    ```
```

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

### Nox Conda and Install Argument Handling

Source: https://nox.thea.codes/en/stable/CHANGELOG

Improvements to how arguments for `conda_install` and `install` are handled, including automatic double-quoting and auto-detection of offline mode for `conda_install`.

```python
# conda_install and install args are now automatically double-quoted when needed.
# Offline mode is now auto-detected by default by conda_install. This allows users to continue executing Nox sessions on already installed environments.
```

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

### Install Nox with Tox Conversion Support

Source: https://nox.thea.codes/en/stable/usage

Installs or upgrades Nox with the necessary extra dependencies to enable the tox.ini to noxfile.py conversion feature.

```shell
pip install --upgrade nox[tox_to_nox]

```

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

### Nox GitHub Actions Integration

Source: https://nox.thea.codes/en/stable/tutorial

Demonstrates how to set up Nox in GitHub Actions for various Python versions, including specific version lists.

```yaml
# setup nox with all active CPython and PyPY versions provided by
# the GitHub Actions environment i.e. 
# python-versions: "3.8, 3.9, 3.10, 3.11, 3.12, pypy-3.8, pypy-3.9, pypy-3.10"
# Any Nox tag will work here
-uses:wntrblm/nox@2024.04.15

# 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@2024.04.15
with:
python-versions:"2.7,3.5,3.11,pypy-3.9"

```

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

### Run Specific Nox Session

Source: https://nox.thea.codes/en/stable/tutorial

Demonstrates how to execute only a specific Nox session using the `--sessions` argument. Nox will create a virtual environment and run the specified session, showing its progress and outcome.

```python
nox --sessions lint
```

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

### Session.install() with Silent Option

Source: https://nox.thea.codes/en/stable/_sources/CHANGELOG.md

Shows how to use the `silent` argument in `session.install()` to suppress output during package installation. This can be useful for cleaner logs when installing many dependencies.

```python
from nox import session

@session
def install_silently(session):
    """Install packages silently."""
    session.install('pytest', silent=True)

```

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

### Passing Positional Arguments with Notify

Source: https://nox.thea.codes/en/stable/_sources/tutorial.rst

Shows how to pass positional arguments to a notified session. The 'prepare_thing' session runs a 'prepare' command and then notifies 'consume_thing' with a path.

```python
@nox.session
def prepare_thing(session):
    thing_path = "./path/to/thing"
    session.run("prepare", "thing", thing_path)
    session.notify("consume_thing", posargs=[thing_path])

@nox.session
def consume_thing(session):
    # The 'consume' command has the arguments
    # sent to it from the 'prepare_thing' session
    session.run("consume", "thing", *session.posargs)
```

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

### Nox Session Install Methods

Source: https://nox.thea.codes/en/stable/_sources/usage.rst

The '--no-install' option causes these session methods to return early, skipping package installation when virtual environments are reused.

```python
session.install
session.conda_install
session.run_install
```

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

### Nox Session Installation Alias

Source: https://nox.thea.codes/en/stable/CHANGELOG

In Nox, `session.install` is now a simple alias for `session.run`. This change streamlines the process of installing packages within a Nox session, making the API more consistent.

```python
def my_session(session):
    session.install("requests") # Equivalent to session.run("pip", "install", "requests")
```

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

### List All Available Nox Sessions

Source: https://nox.thea.codes/en/stable/_sources/CONTRIBUTING.md

Lists all the available sessions that can be run with Nox. This helps in understanding the different testing and linting configurations.

```shell
nox --list-sessions
```

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

### List All Available Nox Tests

Source: https://nox.thea.codes/en/stable/CONTRIBUTING

This command lists all the test sessions that Nox can run. It helps users understand the available testing configurations.

```bash
nox -l
```

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

### UV-Installed Pythons Support

Source: https://nox.thea.codes/en/stable/_sources/CHANGELOG.md

Adds support for using Python interpreters installed via `uv`. This integration allows Nox to leverage `uv` for managing Python environments, potentially improving installation speed and reliability.

```python
# Example usage (conceptual):
# @nox.session(python='uv:3.10')
# def test_with_uv(session):
#     session.install('pytest')
#     session.run('pytest')

```

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

### Noxfile Configuration for Script Mode

Source: https://nox.thea.codes/en/stable/tutorial

This snippet shows the necessary comment and Python code to enable running Nox sessions without the 'nox' command, allowing execution via generalized Python runners. It includes dependencies for Nox and the main execution block.

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

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

```

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

### Run external installation commands in a Nox session

Source: https://nox.thea.codes/en/stable/_sources/tutorial.rst

Executes external commands, such as build tools like CMake, within the Nox session. This is useful for installing non-Python dependencies required for building Python extensions.

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

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

### Nox Python 2.7 Support Removal

Source: https://nox.thea.codes/en/stable/_sources/CHANGELOG.md

Nox no longer supports Python 2.7 for its own installation and operation. While users can still create and run sessions for Python 2.7 projects, Nox itself requires Python 3.5+ to be installed.

```python
# Nox itself requires Python 3.5+.
# You can still run sessions for Python 2.7 projects:
# @nox.session(python="2.7")
# def session_py27(session):
#     # ... session logic for Python 2.7 ...
```
Tokens:
Raw