---
id: tox-docker
version: "5.0.0"
license: unclear
license_treatment: permissive
maintenance: active
---

# tox-docker — Manage lifecycle of docker containers during Tox test runs

License: permissive · Maintenance: active · Downloads: 102.8K/mo

## 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 above — 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

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

- License: not declared (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: active
- Downloads: 102.8K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

tox docker containers, docker integration testing, test environment docker setup, tox plugin docker, containerized test dependencies, docker service testing, tox test infrastructure, docker-testing, tox-plugin, ci-cd

[View on SkillFed](https://skillfed.io/packages/tox-docker) · [View on PyPI](https://pypi.org/project/tox-docker/)