pytest-container

What it is and what it does

pytest-container is a pytest plugin that wraps the complexity of container-based testing. It provides fixtures that automatically pull, launch, and tear down container images, bind exposed ports to free host ports, mount volumes, and wait for containers to become healthy—all without you writing boilerplate. Your test functions receive a testinfra connection object to run assertions inside the running container (checking for files, installed packages, services, etc.), turning container image validation into ordinary pytest tests.

The plugin handles the tedious infrastructure work: finding free ports, managing temporary directories for volumes, cleaning up after tests, orchestrating dependent container builds in the right order, and supporting parallel test execution. It's designed for functional testing of OS container images and verifying that software runs correctly across multiple operating systems or distributions.

Use it for:

• Verify that a Dockerfile produces a working image by testing file presence, package installation, and service startup inside the container.
• Run the same test suite against multiple OS container images to ensure cross-platform compatibility.
• Test multi-container setups by creating and destroying podman pods within pytest fixtures.
• Validate container port bindings and volume mounts by asserting on container state from the host.
• Integrate container image validation into CI/CD pipelines as part of a standard pytest test run.

Worth the install?

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

A pytest plugin that automates container testing by managing container lifecycle, port binding, volume mounting, and health checks, letting you write tests against container images using testinfra.

Yes, if you need to test container images programmatically. The plugin is actively maintained, has low install friction, and solves a real problem—automating container lifecycle management in tests. The LGPL-2.1-or-later license requires source distribution if you modify and redistribute, which is typical for testing tools. No known security vulnerabilities. Suitable for teams building and validating container images as part of their development workflow.

Install

pytest-container on PyPI

pip install pytest-container

uv add pytest-container

poetry add pytest-container

Installing pytest-container

Before you install

Low install friction with a pure-Python wheel distribution. Active maintenance with a recent commit on 2026-03-02 and regular releases; the project has been stable since its first release in 2021-11-19.

License in practice

Licensed under LGPL-2.1-or-later (copyleft). You must distribute source code and license terms with any derivative work, and any modifications must be released under the same or compatible license.

Quickstart

pip install pytest-container

from pytest_container import Container
import pytest

TW = Container(url="registry.opensuse.org/opensuse/tumbleweed:latest")

@pytest.mark.parametrize("container", [TW], indirect=["container"])
def test_etc_os_release_present(container):
    assert container.connection.file("/etc/os-release").exists

Requires a container runtime (Docker or Podman) installed and running on the host system.

Verify before relying

• Whether the package supports both Docker and Podman equally, or if one is preferred.
• Specific Python version compatibility (requires_python is unspecified in metadata).
• Performance characteristics when running tests in parallel with pytest-xdist.

Package facts

Evidence: pytest_container-0.4.4-py3-none-any.whl

Tags

More Testing packages