podman compose: Run Compose Files With Podman
podman compose runs a Compose file with Podman, either through the podman-compose tool or the Docker Compose plugin over the Podman socket.
There are two ways to run Compose with Podman, and they behave slightly differently. Knowing which one you have avoids confusing failures in CI.
What it does
podman compose brings up the services defined in a compose YAML. It dispatches either to podman-compose (a Python reimplementation) or to the external docker compose plugin talking to the Podman socket, depending on what is installed. Both read the standard compose schema.
Common usage
podman compose up -d
podman compose ps
podman compose logs -f web
podman compose down -v
# enable the socket for the docker compose plugin
systemctl --user enable --now podman.socketOptions
| Command/Flag | What it does |
|---|---|
| up -d | Create and start services in the background |
| down -v | Stop services and remove volumes |
| ps | List the services and their status |
| logs -f <svc> | Follow logs for a service |
| -f, --file <path> | Use a specific compose file |
| DOCKER_HOST | Point the compose plugin at the Podman socket |
In CI
For the Docker Compose plugin path, enable the Podman socket (systemctl --user enable --now podman.socket) and set DOCKER_HOST to unix://$XDG_RUNTIME_DIR/podman/podman.sock. For podman-compose, no socket is needed but a few compose features are unsupported, so keep the compose file simple.
Common errors in CI
"Cannot connect to the Docker daemon at unix:///var/run/docker.sock" from the compose plugin means DOCKER_HOST is unset or the Podman socket is not running; enable podman.socket and set DOCKER_HOST. With podman-compose, "unsupported" or ignored keys mean a compose feature the Python tool does not implement. Unqualified image names hit short-name enforcement just like podman pull; fully qualify them.