tox "plugin ... is not compatible" / Config Errors After tox 4 in CI

tox 4 was a full rewrite with a new plugin API and stricter config parsing. A plugin written for tox 3, or a tox.ini using removed/renamed keys, fails when the runner upgrades to tox 4.

What this error means

After a tox upgrade, a run fails with a plugin-incompatibility error or a config-parse error on a key that worked under tox 3. It is deterministic and tied to the tox version, not the project code.

tox output

ROOT: HandledError| plugin tox-poetry is not compatible with this version of tox
# or a config error:
py312: failed with key 'whitelist_externals' has been replaced by 'allowlist_externals'

Common causes

Plugin built for the tox 3 API

tox 4 changed the plugin hook system. A plugin (e.g. an old tox-poetry/tox-conda) that has not been updated cannot load.

Deprecated or renamed tox.ini keys

tox 4 removed or renamed several keys (e.g. whitelist_externals to allowlist_externals) and is stricter about unknown options.

How to fix it

Update the config for tox 4

Rename deprecated keys and remove options tox 4 no longer accepts.

tox.ini

[testenv]
allowlist_externals = make   # was whitelist_externals

Upgrade the plugin or pin tox

Move to a tox-4-compatible plugin release, or pin tox to 3.x until the plugin is updated.

Terminal

# upgrade the plugin
pip install --upgrade tox-poetry
# or pin tox while the plugin catches up
pip install "tox<4"

How to prevent it

Pin the tox major version in CI so an upgrade is deliberate.
Migrate tox.ini keys when adopting tox 4.
Track plugin compatibility before bumping tox.