Podman Compose

1.5.0 · active · verified Thu Apr 16

Podman Compose is a Python-based tool that enables users to define and run multi-container applications using standard `docker-compose.yml` files, with Podman serving as the container engine. It offers a daemonless and rootless alternative to Docker Compose, aiming for compatibility by translating Compose specifications into Podman commands. The current version is 1.5.0, and it generally has an active release cadence with several minor versions released annually, although it is a community-maintained project not officially supported by Red Hat.

Common errors

```
podman-compose: command not found
```
cause The `podman-compose` executable is not in your system's PATH, or the terminal was not restarted after installation.

fix Ensure `pip`'s installation directory (e.g., `~/.local/bin` on Linux) is in your PATH. On Windows, verify `%PATH%` and restart your terminal/IDE. For Debian/RHEL, use `sudo apt install podman-compose` or `sudo dnf install podman-compose` respectively.
```
Error: unqualified-search-registries setting encountered (image 'nginx'). This usually happens when an image name is not fully qualified.
```
cause Image names in `docker-compose.yml` are not fully qualified (e.g., `nginx` instead of `docker.io/library/nginx`). Podman has stricter image pulling policies.

fix Prefix image names with their registry and namespace, e.g., change `image: nginx` to `image: docker.io/library/nginx` or configure `unqualified-search-registries` in Podman's configuration.
```
Error: error creating container: mount: /var/lib/container/overlay/...: permission denied
```
cause Rootless containers often face permission issues when mounting host volumes if the container user doesn't have appropriate permissions or if SELinux is preventing access.

fix For `rootless` Podman, add `:Z` or `:z` to your volume mounts in `docker-compose.yml` (e.g., `- ./data:/app/data:Z`). This tells Podman to relabel the volume with the correct SELinux context. Alternatively, consider `userns_mode: keep-id` for specific services.

Warnings

breaking Older Podman versions (before 3.1.0) required the `podman-compose 0.1.x` branch and had more rootless limitations. The global `-t` option for mapping types is no longer supported in `1.x`.
Fix: Upgrade Podman to 3.4 or newer, use `podman-compose 1.x`, and declare `network_mode: host` directly in your YAML if needed.
gotcha Networking and volume permission differences compared to Docker Compose. Podman Compose often places containers in a Pod by default, which can affect DNS resolution, and rootless containers require specific volume permission handling.
Fix: Explicitly define networks in your `docker-compose.yml` for inter-service communication. For volumes, use `:Z` labels (e.g., `- ./data:/var/lib/data:Z`) or `userns_mode: keep-id` to manage permissions in rootless environments.
gotcha `podman-compose`'s dependency model is stricter than Docker Compose, which can prevent updating a single service without stopping and removing all dependent services.
Fix: Be aware that modifying a service often requires bringing down the entire stack and then bringing it back up. Consider the `podman generate kube` and `podman play kube` commands for more robust orchestration with Kubernetes compatibility if strict dependency management is problematic.
gotcha There are two main tools for running Compose files with Podman: `podman-compose` (this Python script) and `podman compose` (a wrapper around `docker compose` v2 leveraging the Podman socket). `podman compose` takes precedence if `docker compose` is installed.
Fix: Ensure you are using the intended tool. If you want to use the Python-based `podman-compose` specifically, avoid installing `docker compose` v2 or ensure `podman-compose` is prioritized in your PATH if both are present.
gotcha The `podman-compose` project is community-maintained and not officially by Red Hat, unlike `quadlets`, which are Red Hat's recommended approach for Podman container orchestration via systemd. This may lead to `podman-compose` breaking with future Podman changes.
Fix: For production or Red Hat-supported environments, consider migrating to `quadlets` for better long-term maintainability and support. For local development, `podman-compose` remains a viable option.

Install

pip install podman-compose Python Package Index (PyPI)
sudo dnf install podman-compose Fedora/RHEL
sudo apt install podman-compose Ubuntu/Debian

Imports

podman-compose
```
This is primarily a CLI tool; no direct Python imports are commonly used for programmatic interaction.
```
Users typically interact with `podman-compose` via the command line, similar to `docker-compose`.

Quickstart

After creating a `docker-compose.yml` file, use `podman-compose up -d` to start your multi-container application in detached mode. This command translates the Compose file into Podman commands to manage pods, containers, networks, and volumes.

# Create a docker-compose.yml file
# services:
#   web:
#     image: nginx
#     ports:
#       - "80:80"
#   db:
#     image: postgres:15
#     environment:
#       POSTGRES_DB: mydb
#       POSTGRES_USER: user
#       POSTGRES_PASSWORD: password

# Bring up the services
podman-compose up -d

# View logs
podman-compose logs

# Stop and remove services
podman-compose down

view raw JSON →