{"id":8433,"library":"podman-compose","title":"Podman Compose","description":"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.","status":"active","version":"1.5.0","language":"en","source_language":"en","source_url":"https://github.com/containers/podman-compose","tags":["podman","docker-compose","container","orchestration","rootless","daemonless","cli"],"install":[{"cmd":"pip install podman-compose","lang":"bash","label":"Python Package Index (PyPI)"},{"cmd":"sudo dnf install podman-compose","lang":"bash","label":"Fedora/RHEL"},{"cmd":"sudo apt install podman-compose","lang":"bash","label":"Ubuntu/Debian"}],"dependencies":[{"reason":"The underlying container engine. Minimum version 3.4 is recommended for podman-compose 1.x branch.","package":"podman","optional":false},{"reason":"Provides the podman dnsname plugin for container-to-container DNS resolution on CNI networks, unless Podman uses netavark.","package":"podman-plugins","optional":true},{"reason":"Required for parsing YAML compose files.","package":"PyYAML","optional":false},{"reason":"Required for handling .env files in compose configurations.","package":"python-dotenv","optional":false}],"imports":[{"note":"Users typically interact with `podman-compose` via the command line, similar to `docker-compose`.","symbol":"podman-compose","correct":"This is primarily a CLI tool; no direct Python imports are commonly used for programmatic interaction."}],"quickstart":{"code":"# Create a docker-compose.yml file\n# services:\n#   web:\n#     image: nginx\n#     ports:\n#       - \"80:80\"\n#   db:\n#     image: postgres:15\n#     environment:\n#       POSTGRES_DB: mydb\n#       POSTGRES_USER: user\n#       POSTGRES_PASSWORD: password\n\n# Bring up the services\npodman-compose up -d\n\n# View logs\npodman-compose logs\n\n# Stop and remove services\npodman-compose down","lang":"bash","description":"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."},"warnings":[{"fix":"Upgrade Podman to 3.4 or newer, use `podman-compose 1.x`, and declare `network_mode: host` directly in your YAML if needed.","message":"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`.","severity":"breaking","affected_versions":"<1.0.0 (podman-compose) and <3.1.0 (podman)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"`podman-compose`'s dependency model is stricter than Docker Compose, which can prevent updating a single service without stopping and removing all dependent services.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The `podman-compose` executable is not in your system's PATH, or the terminal was not restarted after installation.","error":"podman-compose: command not found"},{"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.","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.","error":"Error: unqualified-search-registries setting encountered (image 'nginx'). This usually happens when an image name is not fully qualified."},{"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.","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.","error":"Error: error creating container: mount: /var/lib/container/overlay/...: permission denied"}]}