Install & Compatibility
Where this runs
tested against v3.2.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
68MB installed
● package 68MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
docker_compose
✓ def test_something(docker_compose):
# Access services via docker_compose fixture
...
pytest automatically injects fixtures like `docker_compose`. Do not explicitly import them from `pytest_docker`.
docker_client
✓ def test_something(docker_client):
# Access Docker client via docker_client fixture
...
pytest automatically injects fixtures like `docker_client`. Do not explicitly import them from `pytest_docker`.
docker_compose_file
✓ import pytest
from pathlib import Path
@pytest.fixture(scope="session")
def docker_compose_file():
return str(Path(__file__).parent / "docker-compose.yml")
This fixture defines the path to your `docker-compose.yml` file. It should be defined in `conftest.py` or a test file to specify the location.
Services
✓ from pytest_docker.plugin import Services
def my_test_function(docker_compose: Services):
# Use for type hinting the docker_compose fixture
...
Recommended for type hinting the `docker_compose` fixture for better IDE support and static analysis.
To use `pytest-docker`, define your Docker Compose services in a `docker-compose.yml` file and then use the `docker_compose` fixture in your tests. You must define a `docker_compose_file` fixture to point to your compose file. This example uses a Redis service:
1. **Create `docker-compose.yml`** (e.g., in the same directory as your test file):
```yaml
services:
redis:
image: redis:latest
ports:
- "6379:6379"
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 1s
timeout: 3s
retries: 5
```
2. **Create `test_redis.py`** with the code above.
3. **Run tests** from your terminal: `pytest`
import pytest
import redis
import time
from pathlib import Path
# This fixture tells pytest-docker where to find docker-compose.yml.
# Place this in your conftest.py or directly in your test file.
@pytest.fixture(scope="session")
def docker_compose_file():
# Assumes docker-compose.yml is in the same directory as this test file.
return str(Path(__file__).parent / "docker-compose.yml")
def test_redis_connection(docker_compose):
# The 'docker_compose' fixture automatically starts services from docker-compose.yml
# Get the host and exposed port for the 'redis' service
host, port = docker_compose.get_service_host_port("redis", 6379)
# Poll until the Redis service is ready to accept connections
_redis_client = None
for _ in range(30): # Try for up to 30 seconds
try:
_redis_client = redis.Redis(host=host, port=port, decode_responses=True)
_redis_client.ping() # Check connection
break
except redis.exceptions.ConnectionError:
time.sleep(1)
else:
pytest.fail("Redis service not ready after 30 seconds")
assert _redis_client is not None
_redis_client.set("mykey", "myvalue")
assert _redis_client.get("mykey") == "myvalue"
_redis_client.close()
Debug
Known issues
breakingVersion 3.0.0 introduced a breaking change by dropping support for Python 3.6 and 3.7. Python 3.8+ is now required, alongside compatibility with pytest v8.fixUpgrade your Python environment to 3.8 or newer and ensure pytest is at a compatible version (e.g., v8+).
affects: >=3.0.0
gotchaThe `docker-compose` Python library dependency version is conditional on your Python interpreter. For Python versions below 3.10, `docker-compose` version 1.x is required. For Python 3.10 and newer, `docker-compose` version 2.x is required. Incorrect versions can lead to `ImportError` or unexpected behavior.fixEnsure the correct `docker-compose` library version is installed for your Python environment. For example, `pip install 'docker-compose>=2.0.0; python_version >= "3.10"'` or `pip install 'docker-compose<2.0; python_version < "3.10"'`.
affects: All versions (dependency constraint)
gotchaAs of v3.2.5, the default `docker_setup_command` for `docker_compose` now includes `--wait`. This command blocks until all services are 'healthy' according to their `healthcheck` definitions. This can significantly increase service startup time during tests if healthchecks are slow or improperly configured.fixReview your `docker-compose.yml` to ensure services have appropriate and efficient `healthcheck` configurations. If strict waiting is not desired, you may need to override the `docker_setup_command` fixture to remove the `--wait` flag.
affects: >=3.2.5
gotchaThe `docker_setup_command` fixture was fixed in v3.2.1 to correctly reference `docker_setup`. Users who might have manually overridden `docker_setup_command` in older versions should verify their fixture names and implementations for compatibility.fixCheck any custom `docker_setup_command` or `docker_setup` fixtures in your `conftest.py`. Ensure they align with the library's expected naming and behavior, especially if you encountered issues with custom setup commands.
affects: Prior to 3.2.1
gotchaThe Docker daemon must be running and accessible for `pytest-docker` to function. This library does not manage the Docker daemon itself, only the containers/services it orchestrates.fixVerify that Docker Desktop or your Docker daemon is running and properly configured before executing tests. Use `docker ps` in your terminal to confirm Docker is operational.
affects: All versions
Errors
Common errors & fixes
fixture 'docker_compose_files' not found
The 'docker_compose_files' pytest fixture, which specifies the path to your docker-compose.yml file(s), has not been defined in your conftest.py.
fixDefine the fixture in your conftest.py file, typically like this:
```python
import pytest
import os
@pytest.fixture(scope='session')
def docker_compose_files(pytestconfig):
return [
os.path.join(str(pytestconfig.rootdir), 'docker-compose.yml')
]
``` docker.errors.DockerException: Error while fetching server API version
The Docker daemon is not running or is not accessible from the environment where pytest-docker is trying to connect.
fixEnsure Docker Desktop (on Windows/macOS) or Docker Engine (on Linux) is running and that your user has appropriate permissions to access the Docker socket.
ERROR: The Compose file './docker-compose.yml' is invalid because: Service 'myservice' has no image or build context specified.
The docker-compose.yml file contains syntax errors or invalid service definitions, preventing Docker Compose from starting the services.
fixReview and correct the syntax and configuration within your docker-compose.yml file according to Docker Compose specifications, paying attention to image or build context definitions.
ModuleNotFoundError: No module named 'pytest_docker'
The 'pytest-docker' package has not been installed in the Python environment where you are running your tests.
fixInstall the package using pip: `pip install pytest-docker`
Upgrade
Version history
3.2.5latest on PyPI · released Nov 12, 2025
Audit
Dependencies
pytestrequiredCore testing framework, `pytest-docker` is a plugin for it.
dockerrequiredPython client for Docker Engine API.
docker-composerequiredPython library to interact with Docker Compose services. The specific version required depends on your Python interpreter: `pytest-docker` requires `docker-compose>=1.29.2,<2.0` for Python versions below 3.10, and `docker-compose>=2.0.0` for Python 3.10 and newer.