# podman compose: Run Compose Files With Podman

> podman compose runs docker-compose.yml files via Podman. Reference for up, down, the podman-compose vs compose plugin split, and the socket errors in CI.

Source: https://latchkey.dev/learn/command-reference/podman-compose  
Updated: 2026-06-30

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

```Terminal
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.socket
```

## Options

| 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.

## FAQ

### podman compose: Run Compose Files With Podman?

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.

### 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt