---
id: pytest-container
version: "0.4.4"
license: LGPL-2.1-or-later
license_treatment: copyleft
maintenance: active
---

# pytest-container — Pytest fixtures for writing container based tests

License: copyleft · Maintenance: active · Downloads: 167.1K/mo

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

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

- License: LGPL-2.1-or-later (copyleft)
- Python support: unspecified
- Install friction: low
- Maintenance: active
- Downloads: 167.1K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

pytest container testing, test docker images with pytest, container integration tests, testinfra pytest plugin, automated container lifecycle testing, multi-container pytest fixtures, container health check testing, container-testing, pytest-plugin, infrastructure-as-code

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