---
id: pytest-docker-tools
version: "3.1.10"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# pytest-docker-tools — Docker integration tests for pytest

License: permissive · Maintenance: active · Downloads: 1.7M/mo

## What it is and what it does

pytest-docker-tools is a fixture factory library that lets you define Docker-based test environments declaratively in pytest, similar to docker-compose.yml syntax. Instead of writing boilerplate code to spin up containers for each test, you define fixtures once in conftest.py and inject them into tests; the library handles creation, teardown, and dependency resolution automatically. It supports fixture scoping (session, module, function), automatic port mapping, environment variable injection, and container restart operations.

The library is built on pytest and docker as its only runtime dependencies, making installation straightforward. It's designed for smoke testing Docker images and integration testing microservices, with explicit support for parallel test execution via pytest-xdist. Fixtures can be overridden per test module, and the library captures Docker logs on test failure for debugging.

Use it for:

- Smoke-test a freshly built Docker image before release to verify it starts and responds correctly.
- Integration test a microservice by spinning up dependent containers (database, cache, mock DNS) per test with automatic cleanup.
- Run parallel integration tests across multiple CPU cores using pytest-xdist, with automatic port and resource name collision avoidance.
- Reuse long-lived containers (session scope) across multiple test modules while recreating module-scoped resources between modules.
- Test container restart behavior and recovery without manual container lifecycle management in test code.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides pytest fixture factories for declaratively defining Docker-based test environments, automating container creation, teardown, and dependency resolution across test scopes.

Yes. The package is actively maintained, has no known vulnerabilities, low install friction, and solves a real problem—eliminating boilerplate for Docker-based testing. It's well-suited for teams running integration or smoke tests against containerized services. The permissive Apache-2.0 license poses no restriction. Install it if you're writing tests that need Docker containers.

## Install

pip install pytest-docker-tools
uv add pytest-docker-tools
poetry add pytest-docker-tools

## Installing pytest-docker-tools

Before you install: Low friction: pure Python wheel with only pytest and docker as runtime dependencies. Active maintenance with a release 24 days ago; repository shows 102 stars and no archived status.

License in practice: Apache-2.0 is permissive; you can use this in commercial projects and modify it freely, with minimal restrictions beyond preserving license notices.

Quickstart:

pip install pytest-docker-tools

# In conftest.py
from pytest_docker_tools import container, fetch

my_image = fetch(repository='redis:latest')
my_container = container(image='{my_image.id}', ports={'11211/tcp': None})

# In test_example.py
def test_redis(my_container):
    port = my_container.ports['11211/tcp'][0]
    # connect and test

Requires Docker daemon running and accessible; pytest must be installed.

Verify before relying:

- Whether fixture scopes (session, module, function) work as documented with pytest-xdist parallelism.
- Performance characteristics when managing many concurrent containers under xdist.
- Compatibility with Docker Desktop vs. other Docker installations.

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 1.7M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

docker pytest fixtures, container integration testing, docker-compose pytest, smoke testing docker images, pytest docker containers, docker test environment automation, container fixture factories, docker-testing, pytest-plugin, integration-testing

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