feat(core): add Podman compatibility (#1028)

Brings _Testcontainers for Python_ to feature parity with
[testcontainers-go](https://golang.testcontainers.org/system_requirements/using_podman/)
and
[testcontainers-java](https://java.testcontainers.org/supported_docker_environment/#podman)
for Podman:

- Detect the runtime at the daemon level (cached).
- Transparently adapt the code paths that differ between Docker and
Podman (compose binary selection, port-binding parsing).
- Keep existing Docker behavior unchanged when Docker is the active
runtime.
- Document the supported setup alongside Docker.

Closes #1027.

---------

Co-authored-by: David Ankin <daveankin@gmail.com>

Author: Tranquility2

core/testcontainers/compose/compose.py

@@ -1,3 +1,4 @@
+import shutil
 import sys
 from dataclasses import asdict, dataclass, field
 from functools import cached_property
@@ -11,7 +12,7 @@
 from types import TracebackType
 from typing import Any, Callable, Literal, Optional, TypeVar, Union, cast
 
-from testcontainers.core.docker_client import DockerClient, get_docker_host_hostname
+from testcontainers.core.docker_client import DockerClient, get_docker_host_hostname, is_podman
 from testcontainers.core.exceptions import ContainerIsNotRunning, NoSuchPortExposed
 from testcontainers.core.inspect import ContainerInspectInfo, _ignore_properties
 from testcontainers.core.waiting_utils import WaitStrategy
@@ -21,6 +22,20 @@
 logger = getLogger(__name__)
 
 
+def _default_compose_binary() -> str:
+    """Return the binary used to drive ``compose`` subcommands.
+
+    Prefers ``docker`` when available; otherwise falls back to ``podman``
+    when the daemon is detected as podman. This means a pure-podman host
+    without the ``podman-docker`` shim works out of the box.
+    """
+    if shutil.which("docker"):
+        return "docker"
+    if is_podman() and shutil.which("podman"):
+        return "podman"
+    return "docker"
+
+
 @dataclass
 class PublishedPortModel:
     """
@@ -38,8 +53,9 @@ def normalize(self) -> "PublishedPortModel":
         # For SSH-based DOCKER_HOST, local addresses (0.0.0.0, 127.0.0.1, localhost, ::, ::1)
         # refer to the remote machine, not the local one.
         # Replace them with the actual remote hostname.
+        # Podman may also return empty string or None for the URL.
         ssh_host = get_docker_host_hostname()
-        if ssh_host and url in ("0.0.0.0", "127.0.0.1", "localhost", "::", "::1"):
+        if ssh_host and (not url or url in ("0.0.0.0", "127.0.0.1", "localhost", "::", "::1")):
             url = ssh_host
         # On Windows, 0.0.0.0 is not usable — replace with 127.0.0.1
         elif system() == "Windows" and url == "0.0.0.0":
@@ -275,9 +291,8 @@ def docker_compose_command(self) -> list[str]:
 
     @cached_property
     def compose_command_property(self) -> list[str]:
-        docker_compose_cmd = (
-            [self.docker_command_path, "compose"] if self.docker_command_path else ["docker", "compose"]
-        )
+        binary = self.docker_command_path or _default_compose_binary()
+        docker_compose_cmd = [binary, "compose"]
         if self.compose_file_name:
             for file in self.compose_file_name:
                 docker_compose_cmd += ["-f", file]

core/testcontainers/core/docker_client.py

@@ -366,6 +366,30 @@ def is_ssh_docker_host() -> bool:
     return get_docker_host_hostname() is not None
 
 
+@ft.lru_cache(maxsize=1)
+def is_podman() -> bool:
+    """Detect whether the configured Docker daemon is actually Podman.
+
+    The result is cached for the lifetime of the process: detection requires a
+    daemon round-trip, and this helper is invoked at test-collection time via
+    ``pytest.mark.skipif`` decorators.
+    """
+    try:
+        # Use docker.from_env() directly rather than DockerClient() so we avoid
+        # the constructor's side effects (DOCKER_HOST mutation, registry login).
+        version = docker.from_env().version()
+    except Exception as e:
+        LOGGER.debug(f"is_podman: failed to query daemon version: {e}")
+        return False
+
+    # Prefer the top-level Platform.Name field (matches testcontainers-go).
+    platform_name = (version.get("Platform") or {}).get("Name", "")
+    if "podman" in platform_name.lower():
+        return True
+    # Fall back to scanning the Components array for older podman versions.
+    return any("podman" in comp.get("Name", "").lower() for comp in version.get("Components") or [])
+
+
 def _sanitize_docker_host(docker_host: str) -> str:
     """
     Sanitize the DOCKER_HOST value for compatibility with the Docker SDK.

core/tests/test_compose.py

@@ -10,10 +10,16 @@
 from pytest_mock import MockerFixture
 
 from testcontainers.compose import DockerCompose, ComposeContainer
+from testcontainers.core.docker_client import is_podman
 from testcontainers.core.exceptions import ContainerIsNotRunning, NoSuchPortExposed
 
 FIXTURES = Path(__file__).parent.joinpath("compose_fixtures")
 
+_skip_if_podman_port_range = pytest.mark.skipif(
+    is_podman(),
+    reason="Podman does not support published port ranges (e.g. '5000-5999')",
+)
+
 
 def test_compose_no_file_name():
     basic = DockerCompose(context=FIXTURES / "basic")
@@ -189,6 +195,7 @@ def test_compose_ports():
 
 
 # noinspection HttpUrlsUsage
+@_skip_if_podman_port_range
 def test_compose_multiple_containers_and_ports():
     """test for the logic encapsulated in 'one' function
 
@@ -286,6 +293,7 @@ def test_exec_in_container():
 
 
 # noinspection HttpUrlsUsage
+@_skip_if_podman_port_range
 def test_exec_in_container_multiple():
     """same as above, except we exec into a particular service"""
     multiple = DockerCompose(context=FIXTURES / "port_multiple")
@@ -390,6 +398,8 @@ def test_compose_profile_support(profiles: Optional[list[str]], running: list[st
         pytest.param("ssh://user@10.0.0.5", "0.0.0.0", "10.0.0.5", id="ssh_replaces_wildcard"),
         pytest.param("ssh://user@10.0.0.5", "127.0.0.1", "10.0.0.5", id="ssh_replaces_loopback"),
         pytest.param("ssh://user@10.0.0.5", "::", "10.0.0.5", id="ssh_replaces_ipv6_any"),
+        pytest.param("ssh://user@10.0.0.5", "", "10.0.0.5", id="ssh_replaces_empty"),
+        pytest.param("ssh://user@10.0.0.5", None, "10.0.0.5", id="ssh_replaces_none"),
         pytest.param("tcp://localhost:2375", "0.0.0.0", "0.0.0.0", id="non_ssh_keeps_original"),
     ],
 )
@@ -410,6 +420,33 @@ def test_compose_normalize_rewrites_local_url_for_ssh_docker_host(
     assert result.PublishedPort == 9999
 
 
+@pytest.mark.parametrize(
+    "docker_on_path, podman_on_path, podman_detected, expected",
+    [
+        pytest.param(True, True, True, "docker", id="docker_wins_over_podman"),
+        pytest.param(False, True, True, "podman", id="podman_when_no_docker_and_podman_daemon"),
+        pytest.param(False, False, True, "docker", id="fallback_to_docker_when_no_podman_binary"),
+    ],
+)
+def test_default_compose_binary(
+    monkeypatch: pytest.MonkeyPatch,
+    docker_on_path: bool,
+    podman_on_path: bool,
+    podman_detected: bool,
+    expected: str,
+) -> None:
+    from testcontainers.compose import compose as compose_module
+
+    paths = {
+        "docker": "/usr/bin/docker" if docker_on_path else None,
+        "podman": "/usr/bin/podman" if podman_on_path else None,
+    }
+    monkeypatch.setattr("testcontainers.compose.compose.shutil.which", lambda name: paths.get(name))
+    monkeypatch.setattr(compose_module, "is_podman", lambda: podman_detected)
+
+    assert compose_module._default_compose_binary() == expected
+
+
 def test_container_info():
     """Test get_container_info functionality"""
     basic = DockerCompose(context=FIXTURES / "basic")

core/tests/test_core_ports.py

@@ -4,15 +4,31 @@
 
 from docker.errors import APIError
 
+from testcontainers.core.docker_client import is_podman
+
 
 @pytest.mark.parametrize(
     "container_port, host_port",
     [
         ("8080", "8080"),
-        ("8125/udp", "8125/udp"),
-        ("8092/udp", "8092/udp"),
-        ("9000/tcp", "9000/tcp"),
-        ("8080", "8080/udp"),
+        pytest.param(
+            "8125/udp",
+            "8125/udp",
+            marks=pytest.mark.skipif(is_podman(), reason="Podman rejects protocol in host_port"),
+        ),
+        pytest.param(
+            "8092/udp",
+            "8092/udp",
+            marks=pytest.mark.skipif(is_podman(), reason="Podman rejects protocol in host_port"),
+        ),
+        pytest.param(
+            "9000/tcp",
+            "9000/tcp",
+            marks=pytest.mark.skipif(is_podman(), reason="Podman rejects protocol in host_port"),
+        ),
+        pytest.param(
+            "8080", "8080/udp", marks=pytest.mark.skipif(is_podman(), reason="Podman rejects protocol in host_port")
+        ),
         (8080, 8080),
         (9000, None),
         ("9009", None),
@@ -42,7 +58,18 @@ def test_docker_container_with_bind_ports(container_port: Union[str, int], host_
     expected = {container_port: [{"HostIp": "", "HostPort": host_port}]}
 
     # compare PortBindings to expected output
-    assert client.containers.get(container_id).attrs["HostConfig"]["PortBindings"] == expected
+    actual = client.containers.get(container_id).attrs["HostConfig"]["PortBindings"]
+    if is_podman():
+        # Normalize Podman differences:
+        # - HostIp '0.0.0.0' vs '' (both mean all interfaces)
+        # - Empty host_port: Podman stores the assigned port, Docker stores ''
+        for bindings in actual.values():
+            for binding in bindings:
+                if binding.get("HostIp") == "0.0.0.0":
+                    binding["HostIp"] = ""
+                if not host_port and binding.get("HostPort", "").isdigit():
+                    binding["HostPort"] = ""
+    assert actual == expected
     container.stop()
 
 

core/tests/test_core_registry.py

@@ -22,16 +22,16 @@
 
 from testcontainers.registry import DockerRegistryContainer
 from testcontainers.core.utils import is_mac
+from testcontainers.core.docker_client import is_podman
 
 
-@pytest.mark.skipif(
-    is_mac(),
-    reason="Docker Desktop on macOS does not support insecure private registries without daemon reconfiguration",
-)
-@pytest.mark.skipif(
-    is_ssh_docker_host(),
-    reason="Remote Docker via SSH requires HTTPS for non-localhost registries; insecure HTTP registries are not accessible",
+_skip_insecure_registry = pytest.mark.skipif(
+    is_mac() or is_podman() or is_ssh_docker_host(),
+    reason="Insecure HTTP registries are not supported without daemon reconfiguration on macOS, Podman, or SSH-based Docker hosts",
 )
+
+
+@_skip_insecure_registry
 def test_missing_on_private_registry(monkeypatch):
     username = "user"
     password = "pass"
@@ -53,14 +53,7 @@ def test_missing_on_private_registry(monkeypatch):
                 wait_for_logs(test_container, "Hello from Docker!")
 
 
-@pytest.mark.skipif(
-    is_mac(),
-    reason="Docker Desktop on macOS does not support local insecure registries over HTTP without modifying daemon settings",
-)
-@pytest.mark.skipif(
-    is_ssh_docker_host(),
-    reason="Remote Docker via SSH requires HTTPS for non-localhost registries; insecure HTTP registries are not accessible",
-)
+@_skip_insecure_registry
 @pytest.mark.parametrize(
     "image,tag,username,password,expected_output",
     [

core/tests/test_docker_client.py

@@ -358,6 +358,39 @@ def test_ssh_docker_host(monkeypatch: pytest.MonkeyPatch) -> None:
     assert client.host() == "10.0.0.1"
 
 
+_PODMAN_DAEMON_ERROR = RuntimeError("daemon unreachable")
+
+
+@pytest.mark.parametrize(
+    "version, expected",
+    [
+        pytest.param({"Platform": {"Name": "Docker Engine - Community"}}, False, id="docker_platform"),
+        pytest.param({"Platform": {"Name": "Podman Engine"}}, True, id="podman_platform"),
+        pytest.param({"Platform": {}, "Components": [{"Name": "podman"}]}, True, id="podman_components_fallback"),
+        pytest.param({}, False, id="empty_version_no_match"),
+        pytest.param(_PODMAN_DAEMON_ERROR, False, id="daemon_error_swallowed"),
+    ],
+)
+def test_is_podman(monkeypatch: pytest.MonkeyPatch, version: object, expected: bool) -> None:
+    from testcontainers.core import docker_client as dc
+
+    dc.is_podman.cache_clear()
+    mock_client = MagicMock()
+    if isinstance(version, Exception):
+        monkeypatch.setattr("testcontainers.core.docker_client.docker.from_env", MagicMock(side_effect=version))
+    else:
+        mock_client.version.return_value = version
+        monkeypatch.setattr("testcontainers.core.docker_client.docker.from_env", lambda: mock_client)
+    try:
+        # Call twice to also assert the lru_cache only hits the daemon once.
+        assert dc.is_podman() is expected
+        assert dc.is_podman() is expected
+        if not isinstance(version, Exception):
+            assert mock_client.version.call_count == 1
+    finally:
+        dc.is_podman.cache_clear()
+
+
 def _mock_docker_context(name: str, host: str) -> MagicMock:
     context = MagicMock()
     context.Name = name

core/tests/test_image.py

@@ -30,8 +30,11 @@ def test_docker_image(test_image_tag: Optional[str], test_cleanup: bool, check_f
             assert image.get_wrapped_image() is not None
             logs = image.get_logs()
             assert isinstance(logs, list), "Logs should be a list"
-            assert logs[0] == {"stream": "Step 1/2 : FROM alpine:latest"}
-            assert logs[3] == {"stream": f'Step 2/2 : CMD echo "{random_string}"'}
+            streams = [entry.get("stream", "").strip() for entry in logs]
+            assert any(s.upper().startswith("STEP 1/2") and "FROM ALPINE:LATEST" in s.upper() for s in streams)
+            assert any(s.upper().startswith("STEP 2/2") and random_string in s for s in streams), (
+                f"Expected step 2 with '{random_string}' in logs: {streams}"
+            )
             with DockerContainer(str(image)) as container:
                 c_c = container._container
                 assert c_c

core/tests/test_network.py

@@ -40,7 +40,7 @@ def test_network_create_errors():
         network.create()
 
     assert excinfo.value.response.status_code == HTTPStatus.CONFLICT
-    excinfo.match(f"network with name {network.name} already exists")
+    excinfo.match(f"network.*{network.name}.*already exists")
     network.remove()
 
 

docs/system_requirements/docker.md

@@ -1,11 +1,51 @@
-# General Docker requirements
+# Supported Docker environments
+
+## Overview
 
 Testcontainers requires a Docker-API compatible container runtime.
 During development, Testcontainers is actively tested against recent versions of Docker on Linux, as well as against Docker Desktop on Mac and Windows.
 These Docker environments are automatically detected and used by Testcontainers without any additional configuration being necessary.
 
-It is possible to configure Testcontainers to work for other Docker setups, such as a remote Docker host or Docker alternatives.
-However, these are not actively tested in the main development workflow, so not all Testcontainers features might be available and additional manual configuration might be necessary. Please see the [Docker host detection](../features/configuration.md#docker-host-detection) section for more information.
+It is possible to configure Testcontainers to work with alternative container runtimes (see further down for specific runtimes, or [Docker host detection](../features/configuration.md#docker-host-detection) for general configuration mechanisms).
+Alternative container runtimes are not actively tested in the main development workflow, so not all Testcontainers features might be available and additional manual configuration might be necessary.
 
 If you have further questions about configuration details for your setup or whether it supports running Testcontainers-based tests,
 please contact the Testcontainers team and other users from the Testcontainers community on [Slack](https://slack.testcontainers.org/).
+
+## Podman
+
+In order to run testcontainers against [Podman](https://podman.io/), the env var below should be set.
+
+Testcontainers auto-detects Podman from the daemon's `version` response and adapts a few behaviors (compose binary selection, port-binding parsing) accordingly.
+
+**Linux (rootless):**
+
+```bash
+systemctl --user start podman.socket
+export DOCKER_HOST="unix://${XDG_RUNTIME_DIR}/podman/podman.sock"
+```
+
+**Linux (rootful):**
+
+```bash
+sudo systemctl start podman.socket
+export DOCKER_HOST="unix:///run/podman/podman.sock"
+```
+
+**macOS:**
+
+```bash
+export DOCKER_HOST="unix://$(podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}')"
+```
+
+You can also persist this in `~/.testcontainers.properties` as `docker.host=...`, or use a Docker context (`docker context use my-podman`).
+
+### Docker Compose with Podman
+
+`DockerCompose` prefers `docker` if it is on `PATH` (e.g. via the `podman-docker` shim). Otherwise, when Podman is detected, it falls back to the `podman` binary. You can always override the binary explicitly:
+
+```python
+DockerCompose(".", docker_command_path="podman")
+```
+
+Note that Podman does not support host port ranges (`published: "5000-5999"`) in compose files.

docs/system_requirements/index.md

@@ -180,4 +180,4 @@ commands = pytest
 
 With any of these, once your environment is set up you can simply `pip install testcontainers` (or use Poetry’s `poetry add --dev testcontainers`) and begin writing your container-backed tests in Python.
 
-See the [General Docker Requirements](docker.md) to continue
+See [Supported Docker environments](docker.md) to continue