tox "py3X: InterpreterNotFound" in CI

tox tried to create a virtualenv for a pyXY environment but could not find a matching interpreter on PATH. The version named in the env factor is simply not installed on the runner.

What this error means

tox reports "py311: InterpreterNotFound: python3.11" (or skips the env) because the runner only provisioned a different Python version.

py311: skipped because could not find python interpreter with spec(s): py311
py311: SKIP
  py311: InterpreterNotFound: python3.11

Common causes

The targeted Python version is not installed

tox env py311 needs python3.11 on PATH; the runner only set up, say, 3.12, so tox cannot find it.

Only one Python was provisioned for a multi-env matrix

A tox config running several pyXY envs needs every interpreter present, but setup-python provisioned just one.

How to fix it

Provision every Python the tox envs need

1. List the Python versions referenced by your tox envlist.
2. Install each with setup-python (it supports multiple versions).
3. Re-run tox so each env finds its interpreter.

- uses: actions/setup-python@v5
  with:
    python-version: |
      3.10
      3.11
      3.12

Run one tox env per matrix job

Map each matrix Python to a single tox env with -e so only one interpreter is required per job.

tox -e py${{ matrix.python-version }}

How to prevent it

• Provision all interpreters referenced by the tox envlist.
• Or fan out one tox env per CI matrix entry.
• Keep the tox envlist and the setup-python versions in sync.

Related guides