tox "command ... is not allowed, use allowlist_externals" in CI

tox runs commands inside its env and warns or errors when a command is not part of the env (e.g. bash, make, docker). tox 4 requires you to list such external programs in allowlist_externals (the renamed whitelist_externals).

What this error means

A tox run fails or warns with command 'make' ... is not allowed, use allowlist_externals to allow it. The command exists on the system but tox refuses to run it because it is not declared.

tox output

py311: commands[0]> make build
ERROR: py311: command 'make' is not allowed, use 'allowlist_externals' to allow it

Common causes

External command not declared

tox only auto-allows programs installed into the env. Anything else (bash, make, docker, git) must be listed in allowlist_externals.

Old whitelist_externals key on tox 4

tox 4 renamed whitelist_externals to allowlist_externals. The old key is ignored, so the command appears undeclared.

How to fix it

Declare the external commands

tox.ini

[testenv]
allowlist_externals =
    make
    bash
commands = make build

Rename whitelist_externals if upgrading to tox 4

Replace every whitelist_externals with allowlist_externals.
List each external program by name (a path or a bare command name).
Prefer invoking tools installed into the env over external ones where possible.

How to prevent it

Use allowlist_externals (tox 4) and list every external command.
Prefer env-installed tools over system commands in test envs.
Pin a tox major version so the config key name is stable.