tox "InterpreterNotFound: pythonX.Y" in CI

A tox environment names a Python version (e.g. py311) that is not installed on the runner, so tox cannot find an interpreter to build that env. The other envs may run fine; only the missing version fails.

What this error means

tox skips or errors a specific env with InterpreterNotFound: python3.11 (or py311: InterpreterNotFound). Envs whose interpreters exist run normally; the one targeting the absent version is the failure.

tox output

py310: commands succeeded
py311: InterpreterNotFound: python3.11
ERROR:   py311: InterpreterNotFound: python3.11

Common causes

The targeted Python version is not installed

The runner has some Pythons but not the exact one a tox env requires, so tox cannot create that environment.

envlist broader than the installed interpreters

A tox envlist spanning several versions runs on a runner that only set up one of them, leaving the others without an interpreter.

How to fix it

Provide every Python the envlist needs

On GitHub Actions, install all targeted versions before running tox.

.github/workflows/ci.yml

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

Or run only the env for the active interpreter

Use a matrix and tox -e (or tox-gh) so each job runs the env matching its installed Python.

Terminal

tox -e py$(python -c "import sys;print(f'{sys.version_info.major}{sys.version_info.minor}')")

How to prevent it

Install every Python version your tox envlist targets in CI.
Use a matrix so each job runs only the env it can satisfy.
Keep the envlist in sync with the interpreters CI provides.