tox-docker

What it is and what it does

tox-docker is a plugin for tox that automates the lifecycle of Docker containers during test execution. Instead of manually starting services before running tests, you declare containers in your tox.ini configuration—specifying images, environment variables, port mappings, volumes, and health checks—and the plugin handles spinning them up before tests run and tearing them down afterward.

It integrates seamlessly into tox's existing workflow: you configure containers with a [docker:container-name] section, reference them in your [testenv] via a docker directive, and the plugin exposes container ports and hostnames as environment variables for your tests to use. It supports multi-stage Dockerfiles, container linking, health checks, and parallel test runs with automatic container name suffixing to avoid port conflicts.

Use it for:

• Integration tests requiring a live PostgreSQL or MySQL database without manual container management.
• Testing microservices that depend on multiple containers (app server, cache, message queue) in a single tox run.
• CI/CD pipelines where you want reproducible test environments without external service setup scripts.
• Local development workflows where tox handles spinning up all test dependencies automatically.
• Verifying application behavior against specific database versions by swapping container images in tox.ini.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A tox plugin that manages Docker container lifecycle during test runs, allowing you to spin up and configure containers (databases, services, etc.) as part of your test environment.

Yes. If you use tox for testing and need Docker containers as part of your test environment, this plugin eliminates manual container orchestration. It's actively maintained, has no known vulnerabilities, carries a permissive license, and low install friction. Install it when your test suite depends on external services (databases, caches, APIs) that you want to manage declaratively.

Install

tox-docker on PyPI

pip install tox-docker

uv add tox-docker

poetry add tox-docker

Installing tox-docker

Before you install

Low install friction with a pure-Python wheel. Actively maintained as of 2026-08-10 with a stable release history since 2017. Requires tox and docker as runtime dependencies, both of which are standard in testing workflows.

License in practice

Licensed under a permissive BSD license, suitable for use in both open-source and commercial projects without significant restrictions.

Quickstart

pip install tox-docker

# In tox.ini:
[testenv]
docker = db
commands = pytest tests

[docker:db]
image = postgres:11-alpine
environment = POSTGRES_PASSWORD=test

Requires Docker daemon to be running and accessible; tox must be installed in the same Python environment.

Verify before relying

• Whether container health checks block test execution reliably across different Docker configurations.
• Performance impact of parallel tox runs with multiple container instances on resource-constrained CI systems.

Package facts

Evidence: tox_docker-5.0.0-py3-none-any.whl

Tags

More Testing packages