Install & Compatibility
Where this runs
tested against v1.6.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 20.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.7s · import 0.000s · 22MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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`.
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
podman-compose --version
Debug
Known issues
breakingOlder 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`.fixUpgrade Podman to 3.4 or newer, use `podman-compose 1.x`, and declare `network_mode: host` directly in your YAML if needed.
affects: <1.0.0 (podman-compose) and <3.1.0 (podman)
gotchaNetworking 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.fixExplicitly 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.
affects: All versions
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.fixBe 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.
affects: All versions
gotchaThere 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.fixEnsure 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.
affects: All versions
gotchaThe `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.fixFor 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.
affects: All versions
Upgrade
Version history
1.6.0latest on PyPI · released Jun 3, 2026
Audit
Dependencies
podmanrequiredThe underlying container engine. Minimum version 3.4 is recommended for podman-compose 1.x branch.
podman-pluginsoptionalProvides the podman dnsname plugin for container-to-container DNS resolution on CNI networks, unless Podman uses netavark.
PyYAMLrequiredRequired for parsing YAML compose files.
python-dotenvrequiredRequired for handling .env files in compose configurations.