testcontainers-postgres
PostgreSQL component of testcontainers-python.
Decision gist · record as of 2026-08-14
Yes, if you use Docker for testing and need PostgreSQL containers. The install friction is low, maintenance is active, and there are no known vulnerabilities. However, the package is at 0.0.1rc1—clarify whether this is stable or abandoned before committing to production CI. Also verify the license before use in proprietary projects, as it is currently undeclared.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires Docker to be running and accessible; testcontainers-core manages container lifecycle via Docker socket (configurable via TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE).
- Low install friction with three straightforward runtime dependencies.
- The package is actively maintained with recent commits.
License · maintenance · safety
(unclear) — License treatment is unclear; the package metadata contains no explicit license declaration. Verify the actual license before using in proprietary or restricted contexts.
last release 2023-01-06 (1316 days) · last repo commit 2026-07-31 · 2,271 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 84,200 downloads/mo, #14,018 on PyPI
Alternatives
Verify before relying
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()- Why the package remains at 0.0.1rc1 despite active maintenance—is this intentional or a pre-release that should have graduated?
- Whether the unclear license is documented elsewhere (e.g., in the repository root or GitHub).
- Compatibility and feature parity with the parent testcontainers-python project's current state.
What it is and what it does
testcontainers-postgres wraps PostgreSQL in a Docker container and exposes it for use in tests. It is a component of the larger testcontainers-python framework, which facilitates functional and integration testing by spinning up ephemeral service containers on demand. The package depends on testcontainers-core (which handles Docker lifecycle and cleanup), sqlalchemy (for connection URL generation), and psycopg2-binary (the PostgreSQL driver). You use it by instantiating a PostgresContainer with a Docker image tag, entering its context manager, and retrieving a sqlalchemy-compatible connection URL—the container starts automatically and tears down when the context exits.
The package is designed to eliminate the need for pre-configured test databases or external services. Configuration is available via environment variables (e.g., TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE, TESTCONTAINERS_RYUK_DISABLED) or runtime settings, allowing control over Docker socket paths, cleanup behavior, and container privileges.
Use it for
- Write integration tests that need a real PostgreSQL database without managing containers manually.
- Run CI/CD pipelines that spin up isolated test databases per test suite without external dependencies.
- Test database migrations and schema changes against a fresh PostgreSQL instance each run.
- Develop multi-service tests where PostgreSQL is one of several containerized services.
- Prototype applications that depend on PostgreSQL without installing it locally.
Worth the install?
AI-flagged interpretation of the facts on this page. Verify before relying on it.
Yes, if you use Docker for testing and need PostgreSQL containers.
The install friction is low, maintenance is active, and there are no known vulnerabilities. However, the package is at 0.0.1rc1—clarify whether this is stable or abandoned before committing to production CI. Also verify the license before use in proprietary projects, as it is currently undeclared.
Install
testcontainers-postgres on PyPI
Before you install
Low install friction with three straightforward runtime dependencies. The package is actively maintained with recent commits.
Requires Docker to be running and accessible; testcontainers-core manages container lifecycle via Docker socket (configurable via TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE).
License in practice
License treatment is unclear; the package metadata contains no explicit license declaration. Verify the actual license before using in proprietary or restricted contexts.
Quickstart
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()Verify before relying
- Why the package remains at 0.0.1rc1 despite active maintenance—is this intentional or a pre-release that should have graduated?
- Whether the unclear license is documented elsewhere (e.g., in the repository root or GitHub).
- Compatibility and feature parity with the parent testcontainers-python project's current state.
Package facts
| License | Not declared unclear |
| Python support | Supports the current Python release >=3.7 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | 3 packagestestcontainers-coresqlalchemypsycopg2-binary |
| Maintenance | Actively maintained 1,316 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 84,200 / month, #14,018 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
Evidence: testcontainers_postgres-0.0.1rc1-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “postgres docker testing”
- testcontainers-postgresProvides a PostgreSQL Docker container wrapper for integration and…
- pg0-embeddedEmbeds a PostgreSQL database directly in Python with zero…
- py-pglitepy-pglite provides a zero-config PostgreSQL testing environment for…
Give your agent the search over MCP, or paste the wish link into any chat.
More Testing packages
Pluggy provides a plugin system that lets you define hook specifications and register implementations to be called in sequence, enabling extensible Python applications without tight coupling.
Install it if you're building an extensible application or framework.
pytest is a testing framework that lets you write test functions using plain assert statements and automatically discovers and runs them, with detailed failure reporting.
virtualenv creates isolated Python environments where packages can be installed independently without affecting the system Python or other projects.
Coverage.py measures which lines of Python code are executed during test runs, reporting coverage percentages and identifying untested code paths.
Install it if you want to measure test completeness or enforce coverage thresholds in your project.
pytest-asyncio is a pytest plugin that enables writing and running async test functions using the asyncio library, allowing developers to await code directly within test cases.
Install it if you write tests for any asyncio-based code.
A pytest plugin that generates test reports in Common Test Report Format (CTRF) as JSON, compatible with pytest-xdist and pytest-playwright for distributed and browser-based testing.
Install it if you need CTRF-formatted test output for CI/CD integration or cross-tool reporting.
See also testcontainers · testcontainers-core · py-pglite · testing.postgresql · testgres · tentaclio-postgres · postgres · pgdb · pg0-embedded · python-on-whales