Project Links

Meta

Author: Sergey Pirogov

Maintainer: Balint Bartha, David Ankin, Vemund Santi

Requires Python: >=3.10

Classifiers

Intended Audience

Developers
Information Technology

License

OSI Approved :: Apache Software License

Operating System

MacOS
Microsoft :: Windows
POSIX
Unix

Programming Language

Python :: 3
Python :: 3.10
Python :: 3.11
Python :: 3.12
Python :: 3.13
Python :: 3.14

Topic

Software Development :: Libraries :: Python Modules

PyPI - Version

Testcontainers Python

testcontainers-python facilitates the use of Docker containers for functional and integration testing.

For more information, see the docs.

Getting Started

>>> from testcontainers.postgres import PostgresContainer
>>> import sqlalchemy

>>> with PostgresContainer("postgres:16") as postgres:
...     engine = sqlalchemy.create_engine(postgres.get_connection_url())
...     with engine.begin() as connection:
...         result = connection.execute(sqlalchemy.text("select version()"))
...         version, = result.fetchone()
>>> version
'PostgreSQL 16...'

The snippet above will spin up a postgres database in a container. The get_connection_url() convenience method returns a sqlalchemy compatible url we use to connect to the database and retrieve the database version.

Contributing / Development / Release

See CONTRIBUTING.md for more details.

Configuration

You can set environment variables to configure the library behaviour:

Env Variable	Example	Description
`TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE`	`/var/run/docker.sock`	Path to Docker's socket used by ryuk
`TESTCONTAINERS_RYUK_PRIVILEGED`	`false`	Run ryuk as a privileged container
`TESTCONTAINERS_RYUK_DISABLED`	`false`	Disable ryuk
`RYUK_CONTAINER_IMAGE`	`testcontainers/ryuk:0.8.1`	Custom image for ryuk
`RYUK_RECONNECTION_TIMEOUT`	`10s`	Reconnection timeout for Ryuk TCP socket before Ryuk reaps all dangling containers

Alternatively you can set the configuration during runtime:

from testcontainers.core import testcontainers_config

testcontainers_config.ryuk_docker_socket = "/home/user/docker.sock"

4.15.0 Jul 24, 2026

4.15.0rc4 Jun 11, 2026

4.15.0rc3 Jun 03, 2026

4.15.0rc2 Apr 30, 2026

4.15.0rc1 Apr 07, 2026

4.3.1rc1 Apr 02, 2024

4.3.0 Apr 01, 2024

4.2.0 Mar 24, 2024

4.2.0rc2 Mar 24, 2024

4.2.0rc1 Mar 23, 2024

4.0.0rc2 Jan 23, 2024

4.0.0rc1 Jan 06, 2023

Wheel compatibility matrix

Platform	Python 3
any

Files in release

testcontainers-4.15.0-py3-none-any.whl (157.0KiB)

testcontainers-4.15.0.tar.gz (93.1KiB)

Extras:

Dependencies:

testcontainers 4.15.0