tox-docker

5.0.0 verified Fri May 01 auth: no python

Manage lifecycle of Docker containers during Tox test runs. Version 5.0.0 introduces a major breaking change: tox-docker is now a plug-in installable via the pyproject.toml [tox.env_run_base] requires or as a plugin. Requires tox 4+.

pip install tox-docker

Common errors

error ModuleNotFoundError: No module named 'tox_docker' ↓

cause tox-docker is not installed or not found by tox.

fix

Install tox-docker: pip install tox-docker. Also ensure you have added 'requires = tox-docker' to your tox configuration.

error tox-docker: Error: Environment '...' does not have a 'docker' key or it is empty ↓

cause The 'docker' option is missing or incorrectly formatted.

fix

Add 'docker = postgres:13-alpine' (or another image) under the [testenv] section.

error TypeError: argument of type 'NoneType' is not iterable ↓

cause Common bug when parsing docker config in tox-docker 5.0.0 with missing required fields.

fix

Ensure your tox configuration includes valid docker entries. Check for syntax errors.

Warnings

breaking tox-docker 5.x dropped support for tox <4.0. Upgrade to tox 4+. ↓

fix Upgrade tox to >=4.0.0 and follow new plugin configuration: add 'requires = tox-docker' to tox.ini or pyproject.toml.

breaking The 'docker' option in testenv now expects image names only; previously you could specify complex options. Use 'docker_compose' for compose files. ↓

fix If you need custom options, switch to docker-compose integration or use the container_options in configuration.

deprecated The 'docker_compose' option is deprecated in 5.x and will be removed in 6.0. Use 'compose' and 'compose_project_name' instead. ↓

fix Rename 'docker_compose' to 'compose' in tox.ini.

gotcha Containers are started for each testenv but not shared across environments. If you need shared containers, use a global docker service approach. ↓

fix Define containers under a global ['docker'] section but note they are still per-environment.

gotcha tox-docker 5.x requires Python 3.9+ and Docker SDK. Ensure docker-py is installed. ↓

fix Run `pip install docker` if not already installed.

Imports

tox_docker
wrong
```
import tox_docker
```
correct
```
from tox_docker import ToxDocker
```
ToxDocker is the plugin class, but typically you don't import directly; the plugin auto-registers.

Quickstart

Configure tox-docker as a plugin, then run tox. Containers defined via `docker` option in testenv are started/teardown automatically.

# In pyproject.toml or tox.ini
# pyproject.toml:
# [tool.tox.env_run_base]
# requires = ["tox-docker"]

# tox.ini:
# [tox]
# requires = tox-docker
# 
# [testenv]
# deps = pytest
# commands = pytest
# docker = postgres:13-alpine  # optional, start containers

# Then run:
# tox