Podman Compose — Run Docker Compose Files with Podman

Introduction

Podman Compose is a tool that implements the Docker Compose specification using Podman as the container runtime. It lets teams reuse existing docker-compose.yml files in rootless, daemonless environments without requiring Docker Engine or Docker Desktop.

What Podman Compose Does

• Parses standard docker-compose.yml files and translates them to Podman commands
• Creates pods to group related containers with shared network namespaces
• Supports volume mounts, environment files, port mappings, and health checks
• Runs containers rootless by default for improved security
• Manages the lifecycle of multi-container applications with up, down, start, stop, and logs commands

Architecture Overview

Podman Compose is a Python script that reads a Compose file, builds a dependency graph of services, and issues Podman CLI commands to create pods, networks, volumes, and containers. Each Compose project maps to a Podman pod where containers share a network namespace, similar to Kubernetes pods. The tool delegates all container operations to the Podman engine, inheriting its rootless, daemonless architecture.

Self-Hosting & Configuration

• Install via pip, pipx, or system package managers on Linux and macOS
• Point to any standard docker-compose.yml file in the current directory
• Use .env files for environment variable substitution just like Docker Compose
• Override service configurations with docker-compose.override.yml files
• Set PODMAN_COMPOSE_PROVIDER to switch between podman pod and flat container modes

Key Features

• Drop-in compatibility with most docker-compose.yml features
• Rootless container execution without requiring elevated privileges
• No background daemon process consuming resources when idle
• Pod-based networking that mirrors Kubernetes pod semantics
• Works alongside Podman Desktop for GUI-based container management

Comparison with Similar Tools

• Docker Compose — requires Docker Engine daemon; Podman Compose runs daemonless with Podman
• Podman generate kube — exports to Kubernetes YAML; Podman Compose uses the Compose file format
• Nerdctl Compose — containerd-based Compose implementation; Podman Compose uses Podman's OCI runtime
• Docker Desktop — proprietary GUI with built-in Compose; Podman Compose is open source and CLI-first
• Kubernetes — full orchestration platform; Podman Compose targets single-host development workflows

FAQ

Q: Does Podman Compose support all Docker Compose features? A: It supports most Compose v2 and v3 features including networks, volumes, depends_on, and healthchecks. Some advanced features like Compose profiles may have partial support.

Q: Can I build images with Podman Compose? A: Yes. Podman Compose delegates image builds to podman build, which supports standard Dockerfiles.

Q: Does it work on macOS? A: Yes, when used with Podman Machine which provides a Linux VM for running containers on macOS.

Q: How is networking different from Docker Compose? A: Podman Compose groups services into a pod with a shared network namespace, so containers communicate via localhost rather than Docker-style DNS service names by default.

Sources

• https://github.com/containers/podman-compose
• https://podman.io