testcontainers
Python library for throwaway instances of anything that can run in a Docker container
Decision gist · record as of 2026-08-14
Yes. Testcontainers is actively maintained, widely used (top 1000 on PyPI with 32406683 monthly downloads), has no known vulnerabilities, and solves a real testing problem—running real service instances in tests without manual Docker management. The Apache-2.0 license is permissive. Install it if you write integration tests and want to avoid mocks or manual container setup.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires Docker to be installed and running; the library communicates with Docker via socket (configurable via TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE environment variable).
- Low install friction; depends on docker, python-dotenv, typing-extensions, urllib3, and wrapt.
- Actively maintained with a recent release 21 days ago and 2271 repository stars.
License · maintenance · safety
Apache-2.0 (permissive) — Apache-2.0 is permissive; you can use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.
last release 2026-07-24 (21 days) · last repo commit 2026-07-31 · 2,271 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 32,406,683 downloads/mo, #775 on PyPI
Alternatives
Verify before relying
from testcontainers.postgres import PostgresContainer
with PostgresContainer("postgres:16") as postgres:
connection_url = postgres.get_connection_url()- Which container types (databases, caches, message brokers) are officially supported beyond PostgreSQL.
- Performance overhead and typical container startup times for common services.
- Whether ryuk cleanup behavior can be customized for specific CI/CD environments.
- Full range of supported container image versions and compatibility guarantees.
What it is and what it does
Testcontainers is a Python library that manages Docker containers as test fixtures, letting you spin up real service instances for integration and functional tests without manual container orchestration. Instead of mocking external services, you get actual running instances that your code talks to directly, making tests more realistic and catching real integration issues.
It handles container lifecycle automatically: starting containers before tests, exposing connection URLs and ports, and cleaning up afterward. The library wraps Docker's socket communication and includes ryuk, a cleanup sidecar that reaps dangling containers if tests crash. You configure it via environment variables (socket path, ryuk behavior) or at runtime, and it supports modern Python versions from 3.10 onward with low install friction—just five runtime dependencies.
Use it for
- Write integration tests against a real PostgreSQL database without managing containers manually.
- Test code that connects to services by spinning up containers per test run.
- Validate database migrations and queries against the actual database engine in CI/CD pipelines.
- Ensure application code works with multiple service versions by running different container images.
- Run functional tests that require real stateful services instead of mocks or stubs.
Worth the install?
AI-flagged interpretation of the facts on this page. Verify before relying on it.
Yes.
Testcontainers is actively maintained, widely used (top 1000 on PyPI with 32406683 monthly downloads), has no known vulnerabilities, and solves a real testing problem—running real service instances in tests without manual Docker management. The Apache-2.0 license is permissive. Install it if you write integration tests and want to avoid mocks or manual container setup.
Install
testcontainers on PyPI
Before you install
Low install friction; depends on docker, python-dotenv, typing-extensions, urllib3, and wrapt. Actively maintained with a recent release 21 days ago and 2271 repository stars. Supports Python 3.10 through 3.14.
Requires Docker to be installed and running; the library communicates with Docker via socket (configurable via TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE environment variable).
License in practice
Apache-2.0 is permissive; you can use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.
Quickstart
from testcontainers.postgres import PostgresContainer
with PostgresContainer("postgres:16") as postgres:
connection_url = postgres.get_connection_url()Verify before relying
- Which container types (databases, caches, message brokers) are officially supported beyond PostgreSQL.
- Performance overhead and typical container startup times for common services.
- Whether ryuk cleanup behavior can be customized for specific CI/CD environments.
- Full range of supported container image versions and compatibility guarantees.
Package facts
| License | Apache-2.0 permissive |
| Python support | Supports the current Python release >=3.10 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | 5 packagesdockerpython-dotenvtyping-extensionsurllib3wrapt |
| Maintenance | Actively maintained 21 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 32,406,683 / month, #775 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Intended Audience :: DevelopersIntended Audience :: Information TechnologyLicense :: OSI Approved :: Apache Software LicenseOperating System :: MacOSOperating System :: Microsoft :: WindowsOperating System :: POSIXOperating System :: UnixProgramming Language :: Python :: 3Programming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.12Programming Language :: Python :: 3.13Programming Language :: Python :: 3.14Topic :: Software Development :: Libraries :: Python Modules |
Evidence: testcontainers-4.15.0-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “throwaway test services”
- testcontainersTestcontainers spins up Docker containers on demand during tests to…
- temp-mailsProvides a unified Python API to generate temporary email addresses…
- mailcheckerValidates email addresses against format rules and checks whether…
Give your agent the search over MCP, or paste the wish link into any chat.
More Python Modules packages
Converts domain names between Unicode and ASCII-compatible encoding (Punycode) according to IDNA 2008 and Unicode Technical Standard 46, with security validation and broader script coverage than the standard library.
Install it if you work with internationalized domain names, need to validate domains, or use HTTP clients that depend on it transitively.
Setuptools is a Python build backend and package management tool that handles building, distributing, and installing Python packages, including support for C/C++ extension modules.
PyYAML parses and emits YAML 1.1 data format, enabling serialization and deserialization of configuration files and Python objects to and from human-readable YAML text.
Pydantic validates Python data structures against type hints, coercing and checking input at runtime to ensure it matches a declared schema.
Provides reusable metadata objects for use with PEP-593 `typing.Annotated` to express common constraints like bounds, collection sizes, and predicates on types.
Install it if you use or build libraries that need to express type constraints in a standardized, inspectable way—or if you want to annotate your own types with…
Provides runtime tools to inspect and introspect Python type annotations, enabling programmatic examination of type hints at execution time.
See also testcontainers-core · testcontainers-postgres · pytest-databases · tox-docker · pytest-container · pytest-mock-resources · prefect-docker · docker · apache-airflow-providers-docker · py-pglite