Podman Compose or Docker Compose: Which should you use in Podman?

While Kubernetes has grown to dominate container orchestration, there is still substantial interest in managing containers on a smaller scale, usually for a single system. For these cases, the tool of choice for many years has been Docker Compose.

In the Podman project, we are frequently asked questions about Docker Compose. Does Podman support Docker Compose? What about Docker Compose v2? What is Podman Compose, and should I use it instead of Docker Compose? Read on to find answers to these questions and details on the Podman team's view of the future.

The history of Docker Compose and Podman Compose

Docker Compose began in 2014 as a project to manage groups of containers based on YAML definitions. This YAML was later given a formal specification, the Compose spec. This specification defines a structured language allowing you to run multiple containers on a single machine easily.

This single-file definition of multiple containers is an alternative to running these containers directly from the command line.

Docker Compose was written in Python and communicated with the Docker daemon using its REST API. When Podman was released in 2018, we focused entirely on compatibility with the Docker command-line interface (CLI) and did not include support for the API. Therefore, Podman initially could not be used with Docker Compose. Many people wanted to use Podman and keep their existing Compose YAML files, so a community project called Podman Compose sprung up. Podman Compose processes the Compose spec and translates it into Podman CLI commands.

However, Podman Compose is not perfect because it implements a subset of the functionality of Docker Compose. Many users wish to continue using Docker Compose and other tools that directly connect to the Docker API. To satisfy our community and customers, Podman added a Docker-compatible API in 2019, but supporting Docker Compose required additional work, which occurred in 2020.

[ Get to know Podman by downloading the free Podman basics cheat sheet. ]

The Docker Compose project had also not been idle. In 2021, the Docker Compose project unveiled a complete rewrite of the tool in Go, called Docker Compose v2.0 (older, v1.x versions are often called docker-compose, while v2.x are called docker compose). The rewrite required additional effort to work with Podman, arriving in Podman v4.1 in 2022 (though support for the Buildkit API is still pending).

Which should you use?

This still does not answer most people's question: Should I use Podman Compose or Docker Compose? Neither project is affiliated with Podman (Podman Compose is a community project, not directly maintained by the Podman team). Both are supported for use with Podman, and the Podman team will fix any bugs in Podman that prevent their use (though bugs in the tools themselves will need to be fixed there).

Podman Compose is better integrated with Podman (as it was designed from the ground up to work with Podman) and makes better use of rootless containers and pods. However, Docker Compose is the more featureful option, being the reference implementation of Compose. As such, the answer to which you should use is "it depends."

[ Getting started with containers? Check out this free course. Deploying containerized applications: A technical overview. ]

Podman Compose is the more native and lightweight solution. Podman Compose executes the Podman command directly, rather than communicating with Podman's API socket. This eliminates the need to run the Podman service to provide the API, saving resources. Because it uses Podman's regular command line and fork-exec model, it is easier to trace and manage on the system. For example, Podman Compose can easily be managed by a systemd unit file.

Docker Compose has more features. It is compatible with Docker and Podman and, therefore, more versatile. Further, it has more users than Podman Compose, is more widely tested, and likely more stable.

Given that there are valid reasons to use both, Podman is committed to supporting both Docker Compose and Podman Compose, including both major versions of Docker Compose.

The future of Podman and Compose

The Podman team is not focused on Compose YAML. Instead, we are hard at work on podman generate kube and podman play kube, which allow Kubernetes YAML to be used directly with Podman in a manner similar to Compose. With these tools, we have the advantage of integration with the broader Kubernetes ecosystem. For example, containers that run on Podman via podman play kube can be easily moved onto an OpenShift (Kubernetes) cluster, or a developer can run a pod that misbehaves in Kubernetes on their laptop to debug issues using podman play kube.

We feel that this integration between Podman and Kubernetes is a powerful combination, and it is what we are focusing our efforts on. At the same time, we recognize that most people are using Compose now and will continue to do so for many years. However, we hope users will choose to convert to podman play kube, perhaps using guides such as From Docker Compose to Kubernetes with Podman. We will support both Docker Compose and Podman Compose with Podman for the foreseeable future.