{"id":1206,"library":"testcontainers","title":"Testcontainers for Python","description":"Testcontainers for Python is a library that provides lightweight, disposable instances of common dependencies (databases, message brokers, web browsers, etc.) for integration testing, leveraging Docker containers. The `testcontainers-core` package, while listed on PyPI, serves as an internal dependency for the main `testcontainers` library, which is the package users should install and interact with directly. The current stable version is 4.14.2, with a regular release cadence including minor and patch updates.","status":"active","version":"4.14.2","language":"en","source_language":"en","source_url":"https://github.com/testcontainers/testcontainers-python","tags":["testing","docker","integration testing","database testing","mocking"],"install":[{"cmd":"pip install testcontainers","lang":"bash","label":"Basic Install"},{"cmd":"pip install 'testcontainers[mysql,postgresql]'","lang":"bash","label":"Install with Database Extras"}],"dependencies":[{"reason":"Required for interacting with the Docker daemon.","package":"docker","optional":false},{"reason":"A small, cleanly self-contained module for decorators, used internally.","package":"wrapt","optional":false},{"reason":"Required for database-specific containers (e.g., MySQLContainer, PostgreSQLContainer) if you use their `get_connection_url()` methods.","package":"sqlalchemy","optional":true}],"imports":[{"note":"Even though 'testcontainers-core' is a package, its components are exposed through the main 'testcontainers' namespace.","wrong":"from testcontainers_core.container import DockerContainer","symbol":"DockerContainer","correct":"from testcontainers.core.container import DockerContainer"},{"note":"Common wait strategy for checking container logs.","symbol":"wait_for_log","correct":"from testcontainers.core.waiting_it import wait_for_log"},{"note":"Specific container implementations are typically found in submodules.","symbol":"MySQLContainer","correct":"from testcontainers.mysql import MySQLContainer"}],"quickstart":{"code":"from testcontainers.core.container import DockerContainer\nfrom testcontainers.core.waiting_it import wait_for_log\n\n# Start a simple Alpine container that outputs a message after a delay\n# using a specific version for stability\nwith DockerContainer(\"alpine:3.17.3\") \\\n    .with_command(\"sh -c 'sleep 2 && echo \\\"Container is ready!\\\" && tail -f /dev/null'\") \\\n    .with_wait_for_service(wait_for_log(\"Container is ready!\", timeout=10)) as alpine_container:\n\n    print(\"Alpine container started and 'Container is ready!' message detected.\")\n    # You can access container logs for verification\n    logs = alpine_container.get_logs()\n    if b\"Container is ready!\" in logs:\n        print(\"Successfully found 'Container is ready!' in logs.\")\n    else:\n        print(\"Error: 'Container is ready!' not found in logs.\")\n    assert b\"Container is ready!\" in logs, \"Expected log message not found.\"\n\nprint(\"Container stopped and removed.\")","lang":"python","description":"This quickstart demonstrates how to use a generic `DockerContainer` with a custom command and a `wait_for_log` strategy to ensure the container is ready. The container automatically stops and cleans up upon exiting the `with` block."},"warnings":[{"fix":"Ensure Docker Desktop or a Docker daemon service is running and configured correctly for your environment.","message":"The Docker daemon must be running for Testcontainers to function. If Docker is not available or accessible, container instantiation will fail.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Migrate to `with_wait_for_service()` and use explicit wait strategies like `wait_for_log()`, `wait_for_http()`, `ExecWaitStrategy`, etc. (e.g., `container.with_wait_for_service(wait_for_log(\"message\"))`).","message":"Older decorator-based wait strategies (e.g., `@wait_for`) have been deprecated and removed from core. Using them will lead to errors.","severity":"deprecated","affected_versions":">=4.13.2"},{"fix":"Always install `testcontainers` (e.g., `pip install testcontainers`). Imports for core components like `DockerContainer` are still made from `testcontainers.core.container`.","message":"Do NOT install or use the `testcontainers-core` package directly. It is an internal dependency of the main `testcontainers` library, which is the package intended for user installation and interaction. Installing `testcontainers-core` will result in an outdated and non-functional setup.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Monitor your system resources during tests. Ensure containers are properly cleaned up (using `with` blocks or `stop()/remove()`) to prevent resource leaks. Consider using smaller base images where possible.","message":"Testcontainers relies on Docker, and running multiple or complex containers can consume significant system resources (CPU, RAM, disk I/O).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always pin container image versions (e.g., `mysql:8.0.36`, `alpine:3.17.3`) to ensure your tests are stable and reproducible across different environments and runs.","message":"Using untagged or `latest` Docker images can lead to non-reproducible test failures, as the image content can change unexpectedly.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'4.14.2':65 'broker':20 'browser':22 'cadenc':70 'common':16 'contain':29 'core':33 'current':61 'databas':18,80 'depend':17,43 'direct':59 'dispos':13 'docker':28,77 'etc':23 'includ':71 'instal':55 'instanc':14 'integr':25,78 'interact':57 'intern':42 'leverag':27 'librari':9,48 'lightweight':12 'list':36 'main':46 'messag':19 'minor':72 'mock':82 'packag':34,52 'patch':74 'provid':11 'pypi':38 'python':3,6 'regular':68 'releas':69 'serv':39 'stabl':62 'test':26,76,79,81 'testcontain':1,4,32,47 'testcontainers-cor':31 'updat':75 'user':53 'version':63 'web':21","created_at":"2026-04-05T14:32:40.551582+00:00","updated_at":"2026-04-20T18:44:35.264955+00:00","problems":[],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"4.14.2","cli_name":"","cli_version":null,"type":"library","homepage":"https://testcontainers.com","github":null,"docs":null,"changelog":null,"pypi":null,"npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing","devops","database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-10","next_check":"2026-07-13","install_tag":"verified"}}