testcontainers

Python library for throwaway instances of anything that can run in a Docker container

testcontainers Permissive license Apache-2.0 Active ★ 2,271 v4.15.0 released 2026-07-24

Install

testcontainers on PyPI

pip

pip install testcontainers

uv

uv add testcontainers

poetry

poetry add testcontainers

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 — docker, python-dotenv, typing-extensions, urllib3, wrapt
Maintenance	actively maintained — 20 days since the last release
Last repo commit	2026-07-31
First released	2016-08-21
Popularity	one of the top 1,000 most-downloaded packages on PyPI (30-day window, as of 2026-08-13)
Known vulnerabilities	none known (OSV.dev, checked 2026-08-13)

Evidence: testcontainers-4.15.0-py3-none-any.whl

Keywords: docker, logging, test automation, testing

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

About testcontainers

from the package's own PyPI description — quoted content, verbatim

uv (image) Ruff (image) PyPI - Version (image) PyPI - License (image) PyPI - Python Version (image) codecov (image) Core Tests (image) ![Community...

Read as markdown · JSON record · Source repository · Homepage

AI interpretation — verify before relying

AI-generated interpretation of the package facts above; every digit, version, license, or vulnerability id it cites is grounded in the facts already shown on this page

Testcontainers provides a Python library for spinning up Docker containers during functional and integration tests, enabling you to test against real database instances and other services without mocking.

Low friction install with five runtime dependencies including docker and python-dotenv. Active maintenance with a release 20 days ago and 2271 GitHub stars. Supports Python 3.10–3.14.

Licensed under Apache-2.0 (permissive), allowing commercial and private use with minimal restrictions beyond attribution and liability disclaimers.

Usage

from testcontainers.postgres import PostgresContainer

with PostgresContainer("postgres:16") as postgres:
    connection_url = postgres.get_connection_url()

Docker daemon must be running and accessible; requires Python 3.10 or later.

Verdict: Testcontainers is a mature, actively maintained library for Docker-based integration testing with no known vulnerabilities. Apache-2.0 licensing and low install friction make it suitable for most projects. Requires Docker availability and Python 3.10+.

Needs verification

Whether the library's ryuk cleanup mechanism has known limitations or failure modes in CI/CD environments.
Performance characteristics when spinning up many containers in parallel test suites.
Compatibility with non-standard Docker socket configurations across different platforms.

docker containers for testingintegration testing with databasesthrowaway test instancesfunctional testing dockertest automation with containerstesting with dockertestcontainers python