{"library":"testcontainers","title":"Testcontainers Python","description":"Testcontainers Python is an open-source library that provides lightweight, disposable instances of common databases, message brokers, web browsers, or any service that can run in a Docker container, for development and testing. It simplifies integration testing by provisioning on-demand containers. The library is actively maintained, with frequent releases (typically monthly or bi-monthly), and is currently at version 4.14.2.","status":"active","version":"4.14.2","language":"en","source_language":"en","source_url":"https://github.com/testcontainers/testcontainers-python","tags":["testing","docker","integration testing","containers","ci/cd"],"install":[{"cmd":"pip install testcontainers","lang":"bash","label":"Core library"},{"cmd":"pip install 'testcontainers[postgres]'","lang":"bash","label":"With specific module (e.g., PostgreSQL)"}],"dependencies":[{"reason":"Required to interact with the Docker daemon; typically installed via `pip install docker` or provided by your system's Python environment.","package":"docker","optional":false},{"reason":"Required for `testcontainers.compose.DockerCompose` functionality.","package":"docker-compose","optional":true},{"reason":"A database driver (e.g., psycopg for PostgreSQL) is required in your project to connect to the database container.","package":"psycopg","optional":true},{"reason":"An ORM/SQL toolkit (e.g., SQLAlchemy) is commonly used with database containers.","package":"sqlalchemy","optional":true}],"imports":[{"symbol":"DockerContainer","correct":"from testcontainers.core.container import DockerContainer"},{"symbol":"PostgresContainer","correct":"from testcontainers.postgres import PostgresContainer"},{"symbol":"DockerCompose","correct":"from testcontainers.compose import DockerCompose"},{"note":"Specific module containers are imported directly from their module, not from `testcontainers.core`.","wrong":"from testcontainers.core.kafka import KafkaContainer","symbol":"KafkaContainer","correct":"from testcontainers.kafka import KafkaContainer"}],"quickstart":{"code":"import os\nfrom testcontainers.postgres import PostgresContainer\nimport psycopg\n\n# Example of using PostgresContainer in a test context\ndef test_postgres_container_starts():\n    # Use a specific image version for reproducibility\n    # The database driver (psycopg) is expected to be installed in your environment\n    with PostgresContainer(\"postgres:16\") as postgres:\n        connection_url = postgres.get_connection_url()\n        print(f\"PostgreSQL container started, connection URL: {connection_url}\")\n        # Connect to the database\n        with psycopg.connect(connection_url) as conn:\n            with conn.cursor() as cur:\n                cur.execute(\"SELECT 1\")\n                result = cur.fetchone()\n                assert result == (1,)\n        print(\"Successfully connected and executed a query.\")\n\nif __name__ == \"__main__\":\n    # Ensure Docker is running before executing\n    # In a real test suite, this would typically be run by pytest\n    test_postgres_container_starts()","lang":"python","description":"This quickstart demonstrates how to spin up a PostgreSQL container using `PostgresContainer` as a context manager. It connects to the database using `psycopg` and executes a simple query to verify connectivity. The container is automatically started before the `with` block and torn down afterward, ensuring a clean and isolated environment."},"warnings":[{"fix":"Update your `pip install` commands and `requirements.txt` to use the main `testcontainers` package with bracketed extras (e.g., `testcontainers[mysql,kafka]`).","message":"With version 4.0.0, the `testcontainers-*` individual PyPI packages (e.g., `testcontainers-postgres`) were deprecated. Users must now install the main `testcontainers` package and specify required modules as 'extras' (e.g., `pip install 'testcontainers[postgres]'`).","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure Docker is installed and running. For CI/CD, confirm that `/var/run/docker.sock` is mounted or `DOCKER_HOST` is correctly set within the container where tests run. Check Docker permissions for the user executing the tests.","message":"Testcontainers requires a running Docker daemon accessible by the Python process. Common issues include Docker not running, insufficient user permissions, or misconfigured DOCKER_HOST environment variables, especially in CI/CD environments (e.g., Docker-in-Docker setups).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always specify a fixed, known-good version tag for Docker images (e.g., `PostgresContainer('postgres:16')`) to ensure reproducible test environments.","message":"Using ':latest' Docker image tags can lead to flaky or unpredictable tests, as the 'latest' image can change without notice and introduce breaking changes. It's a best practice to pin specific image versions (e.g., 'postgres:16').","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review container initialization logic. Where possible, adopt the enhanced `WaitStrategy` classes or ensure built-in container modules (e.g., `PostgresContainer`) are using the latest internal waiting mechanisms, avoiding manual `time.sleep()` calls.","message":"Older wait strategies, particularly those using decorators for `wait_for_container_ready` or custom, less explicit waiting logic, are being superseded. Newer versions of Testcontainers encourage or internally use explicit `WaitStrategy` classes and `ExecWaitStrategy`.","severity":"deprecated","affected_versions":">=4.13.0"},{"fix":"When relying on community modules, consult the changelog for each `testcontainers` minor update. Pin the `testcontainers` version in your `requirements.txt` to mitigate unexpected behavior if a module breaks compatibility.","message":"While the `core` package adheres to Semantic Versioning, community modules (e.g., `testcontainers[mysql]`) are supported on a 'best-effort' basis. Breaking changes may occur in these modules with minor version updates of the main `testcontainers` package.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Prefer using `with SomeContainer(...) as container:` for automatic cleanup. For non-context-manager usage or in `pytest` fixtures, ensure `container.stop()` is called in a `finally` block or `addfinalizer` to explicitly manage container lifecycle.","message":"Though Testcontainers uses Ryuk for automatic container cleanup, it's good practice to ensure containers are explicitly stopped and removed, especially in complex `pytest` fixtures without `yield` or for custom `DockerContainer` instances not using context managers, to prevent resource leakage.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}