# Podman Compose — Run Docker Compose Files with Podman

> Use existing docker-compose.yml files with Podman as the container engine, enabling rootless multi-container applications without the Docker daemon.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

# Podman Compose — Run Docker Compose Files with Podman

## Quick Use
```bash
pip install podman-compose
# use your existing docker-compose.yml
podman-compose up -d
podman-compose logs -f
podman-compose down
```

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

---
Source: https://tokrepo.com/en/workflows/podman-compose-run-docker-compose-files-podman-028ac49d
Author: Script Depot