[](https://python-poetry.org/)
[](https://github.com/astral-sh/ruff)
[](https://github.com/testcontainers/testcontainers-python/blob/main/LICENSE)
[](https://pypi.python.org/pypi/testcontainers)
[](https://codecov.io/gh/testcontainers/testcontainers-python)
[](http://testcontainers-python.readthedocs.io/en/latest/?badge=latest)
[](https://codespaces.new/testcontainers/testcontainers-python)
# Testcontainers Python
`testcontainers-python` facilitates the use of Docker containers for functional and integration testing.
For more information, see [the docs][readthedocs].
[readthedocs]: https://testcontainers-python.readthedocs.io/en/latest/
## Getting Started
```pycon
>>> 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](.github/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:
```python
from testcontainers.core import testcontainers_config
testcontainers_config.ryuk_docker_socket = "/home/user/docker.sock"
```
Raw data
{
"_id": null,
"home_page": null,
"name": "testcontainers",
"maintainer": "Balint Bartha",
"docs_url": null,
"requires_python": "<4.0,>=3.9.2",
"maintainer_email": "totallyzen@users.noreply.github.com",
"keywords": "testing, logging, docker, test automation",
"author": "Sergey Pirogov",
"author_email": "automationremarks@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/18/51/edac83edab339d8b4dce9a7b659163afb1ea7e011bfed1d5573d495a4485/testcontainers-4.13.2.tar.gz",
"platform": null,
"description": "[](https://python-poetry.org/)\n[](https://github.com/astral-sh/ruff)\n\n[](https://github.com/testcontainers/testcontainers-python/blob/main/LICENSE)\n[](https://pypi.python.org/pypi/testcontainers)\n[](https://codecov.io/gh/testcontainers/testcontainers-python)\n\n\n[](http://testcontainers-python.readthedocs.io/en/latest/?badge=latest)\n\n[](https://codespaces.new/testcontainers/testcontainers-python)\n\n# Testcontainers Python\n\n`testcontainers-python` facilitates the use of Docker containers for functional and integration testing.\n\nFor more information, see [the docs][readthedocs].\n\n[readthedocs]: https://testcontainers-python.readthedocs.io/en/latest/\n\n## Getting Started\n\n```pycon\n>>> from testcontainers.postgres import PostgresContainer\n>>> import sqlalchemy\n\n>>> with PostgresContainer(\"postgres:16\") as postgres:\n... engine = sqlalchemy.create_engine(postgres.get_connection_url())\n... with engine.begin() as connection:\n... result = connection.execute(sqlalchemy.text(\"select version()\"))\n... version, = result.fetchone()\n>>> version\n'PostgreSQL 16...'\n```\n\nThe 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.\n\n## Contributing / Development / Release\n\nSee [CONTRIBUTING.md](.github/CONTRIBUTING.md) for more details.\n\n## Configuration\n\nYou can set environment variables to configure the library behaviour:\n\n| Env Variable | Example | Description |\n| --------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------- |\n| `TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE` | `/var/run/docker.sock` | Path to Docker's socket used by ryuk |\n| `TESTCONTAINERS_RYUK_PRIVILEGED` | `false` | Run ryuk as a privileged container |\n| `TESTCONTAINERS_RYUK_DISABLED` | `false` | Disable ryuk |\n| `RYUK_CONTAINER_IMAGE` | `testcontainers/ryuk:0.8.1` | Custom image for ryuk |\n| `RYUK_RECONNECTION_TIMEOUT` | `10s` | Reconnection timeout for Ryuk TCP socket before Ryuk reaps all dangling containers |\n\nAlternatively you can set the configuration during runtime:\n\n```python\nfrom testcontainers.core import testcontainers_config\n\ntestcontainers_config.ryuk_docker_socket = \"/home/user/docker.sock\"\n```\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Python library for throwaway instances of anything that can run in a Docker container",
"version": "4.13.2",
"project_urls": {
"GitHub": "https://github.com/testcontainers/testcontainers-python",
"Issue Tracker": "https://github.com/testcontainers/testcontainers-python/issues"
},
"split_keywords": [
"testing",
" logging",
" docker",
" test automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2a5e73aa94770f1df0595364aed526f31d54440db5492911e2857318ed326e51",
"md5": "cae089dae9ccd0a4b5d220642ec860f8",
"sha256": "0209baf8f4274b568cde95bef2cadf7b1d33b375321f793790462e235cd684ee"
},
"downloads": -1,
"filename": "testcontainers-4.13.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cae089dae9ccd0a4b5d220642ec860f8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9.2",
"size": 124771,
"upload_time": "2025-10-07T21:53:05",
"upload_time_iso_8601": "2025-10-07T21:53:05.937579Z",
"url": "https://files.pythonhosted.org/packages/2a/5e/73aa94770f1df0595364aed526f31d54440db5492911e2857318ed326e51/testcontainers-4.13.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1851edac83edab339d8b4dce9a7b659163afb1ea7e011bfed1d5573d495a4485",
"md5": "ff954b12122b810863eef8a7e7c135b9",
"sha256": "2315f1e21b059427a9d11e8921f85fef322fbe0d50749bcca4eaa11271708ba4"
},
"downloads": -1,
"filename": "testcontainers-4.13.2.tar.gz",
"has_sig": false,
"md5_digest": "ff954b12122b810863eef8a7e7c135b9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9.2",
"size": 78692,
"upload_time": "2025-10-07T21:53:07",
"upload_time_iso_8601": "2025-10-07T21:53:07.531926Z",
"url": "https://files.pythonhosted.org/packages/18/51/edac83edab339d8b4dce9a7b659163afb1ea7e011bfed1d5573d495a4485/testcontainers-4.13.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-07 21:53:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "testcontainers",
"github_project": "testcontainers-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "mkdocs",
"specs": [
[
"==",
"1.3.0"
]
]
},
{
"name": "mkdocs-codeinclude-plugin",
"specs": [
[
"==",
"0.2.0"
]
]
},
{
"name": "mkdocs-material",
"specs": [
[
"==",
"8.1.3"
]
]
},
{
"name": "mkdocs-markdownextradata-plugin",
"specs": [
[
"==",
"0.2.5"
]
]
}
],
"lcname": "testcontainers"
}
JSON
