nox "Python X.Y not found" / Session Failures in CI

A nox session either could not find the Python it is parametrized on, or its command exited non-zero. Like tox, nox builds a per-session venv for a named interpreter; a missing one (or a failing command) fails the session.

What this error means

nox reports Python 3.11 not found; skipping session (and fails if --error-on-missing-interpreters is set), or a session ends with a non-zero command and Session ... failed. The summary lists which session failed.

nox output

nox > Python 3.11 not found; skipping session tests-3.11.
nox > Running session lint
nox > ruff check .
nox > Command ruff check . failed with exit code 1
nox > Session lint failed.

Common causes

The session’s interpreter is not installed

A @nox.session(python="3.11") needs Python 3.11 on PATH. If it is absent, nox skips (or errors with --error-on-missing-interpreters).

A session command failed

The tool the session runs (ruff, pytest, mypy) exited non-zero, so nox marks the session failed - the real cause is that command’s output.

How to fix it

Install the interpreters the sessions need

.github/workflows/ci.yml

- uses: actions/setup-python@v5
  with:
    python-version: |
      3.11
      3.12
- run: pip install nox && nox

Read the failing command and fix it

Find the Command ... failed line - the tool it ran is the real failure.
Run that session alone with nox -s <name> to iterate.
Set --error-on-missing-interpreters only once all interpreters are guaranteed present.

How to prevent it

Install every interpreter your nox sessions are parametrized on.
Run sessions individually (nox -s) to isolate failures.
Pin session tools so their behavior is stable across runs.