testcontainers-python facilitates the use of Docker containers for functional and integration testing. The collection of packages currently supports the following features.

.. toctree::

    core/README
    arangodb/README
    azurite/README
    clickhouse/README
    compose/README
    elasticsearch/README
    google/README
    kafka/README
    keycloak/README
    localstack/README
    minio/README
    mongodb/README
    mssql/README
    mysql/README
    neo4j/README
    nginx/README
    opensearch/README
    oracle/README
    postgres/README
    rabbitmq/README
    redis/README
    selenium/README

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

>>> postgres_container = PostgresContainer("postgres:9.5")
>>> with postgres_container as postgres:
...     e = sqlalchemy.create_engine(postgres.get_connection_url())
...     result = e.execute("select version()")
...     version, = result.fetchone()
>>> version
'PostgreSQL 9.5...'

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. More extensive documentation can be found at Read The Docs.

The suite of testcontainers packages is available on PyPI, and individual packages can be installed using pip. We recommend installing the package you need by running pip install testcontainers-<feature>, e.g., pip install testcontainers-mysql.

For backwards compatibility, packages can also be installed by specifying extras, e.g., pip install testcontainers[mysql].

When trying to launch a testcontainer from within a Docker container two things have to be provided:

1. The container has to provide a docker client installation. Either use an image that has docker pre-installed (e.g. the official docker images) or install the client from within the Dockerfile specification.
2. The container has to have access to the docker daemon which can be achieved by mounting /var/run/docker.sock or setting the DOCKER_HOST environment variable as part of your docker run command.

We recommend you use a virtual environment for development. Note that a python version >=3.7 is required. After setting up your virtual environment, you can install all dependencies and test the installation by running the following snippet.

pip install -r requirements/$(python -c 'import sys; print("%d.%d" % sys.version_info[:2])').txt
pytest -s

We use pip-tools to resolve and manage dependencies. If you need to add a dependency to testcontainers or one of the extras, modify the setup.py as well as the requirements.in accordingly and then run pip install pip-tools followed by make requirements to update the requirements files.

You can contribute a new container in three steps:

1. Create a new module at testcontainers/[my fancy container].py that implements the new functionality.
2. Create a new test module at tests/test_[my fancy container].py that tests the new functionality.
3. Add [my fancy container] to the list of test components in the GitHub Action configuration at .github/workflows/main.yml.