Python "tox: ERROR could not install deps" in CI

tox reports ERROR: could not install deps when the pip install for a test environment fails. The real cause is in the pip output above: an unresolvable requirement, an unreachable index, or a wheel build failure.

What this error means

A tox run ends with "ERROR: could not install deps [...]; v = InvocationError(...)" after pip output showing the underlying install failure.

python

ERROR: could not install deps [-r requirements.txt]; v = InvocationError('.../python -m pip install -r requirements.txt', 1)

Common causes

An unresolvable or unreachable requirement

A pinned version does not exist, or a private index is unreachable from the tox env.

A dependency wheel failed to build inside the env

A package with no matching wheel tried to build from source and failed for missing toolchain.

How to fix it

Read the pip output and fix the deps list

Scroll above the tox error to the pip output that names the failing package.
Correct the requirement, add the index URL, or install the needed build toolchain in the env.
Re-run with tox -e <env> -v for more detail if the cause is unclear.

Terminal

tox -e py311 -v

How to prevent it

Validate requirements resolve before pushing.
Provide index URLs/credentials to tox via passenv where needed.
Prefer wheels and pin reproducible versions.