[](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",
"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/d3/62/01d9f648e9b943175e0dcddf749cf31c769665d8ba08df1e989427163f33/testcontainers-4.12.0.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": null,
"summary": "Python library for throwaway instances of anything that can run in a Docker container",
"version": "4.12.0",
"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": "b2e89e2c392e5d671afda47b917597cac8fde6a452f5776c4c9ceb93fbd2889f",
"md5": "71209355e055c778afa996c8bc2c0538",
"sha256": "26caef57e642d5e8c5fcc593881cf7df3ab0f0dc9170fad22765b184e226ab15"
},
"downloads": -1,
"filename": "testcontainers-4.12.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "71209355e055c778afa996c8bc2c0538",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 111791,
"upload_time": "2025-07-21T20:32:25",
"upload_time_iso_8601": "2025-07-21T20:32:25.038109Z",
"url": "https://files.pythonhosted.org/packages/b2/e8/9e2c392e5d671afda47b917597cac8fde6a452f5776c4c9ceb93fbd2889f/testcontainers-4.12.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d36201d9f648e9b943175e0dcddf749cf31c769665d8ba08df1e989427163f33",
"md5": "823e2821f08c971bf223e1295ad3cdd8",
"sha256": "13ee89cae995e643f225665aad8b200b25c4f219944a6f9c0b03249ec3f31b8d"
},
"downloads": -1,
"filename": "testcontainers-4.12.0.tar.gz",
"has_sig": false,
"md5_digest": "823e2821f08c971bf223e1295ad3cdd8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 66631,
"upload_time": "2025-07-21T20:32:26",
"upload_time_iso_8601": "2025-07-21T20:32:26.370200Z",
"url": "https://files.pythonhosted.org/packages/d3/62/01d9f648e9b943175e0dcddf749cf31c769665d8ba08df1e989427163f33/testcontainers-4.12.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-21 20:32:26",
"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
