Podman Compose - Managing Containers

May 12, 2022


Podman is a daemonless engine for OCI container management. It aims to provide a one-to-one replacement for all Docker functionalities by directly implementing relevant container management features or using other utilities such as Buildah and Skopeo.

In this article, you will learn about Podman Compose, a tool for running multi-container apps similar to Docker Compose.

Podman Compose - managing containers.


What is Podman Compose?

Podman Compose is a Docker Compose implementation for Podman. It is a tool that facilitates the deployment of interdependent containers by grouping all the necessary instructions in a single YAML file. Podman Compose is designed to offer full compatibility with Docker Compose YAML files, with added functionalities that handle Podman's rootless and daemonless nature.

How to Install Podman Compose

Install Podman Compose using the pip package manager or a Python script. Fedora repositories contain the podman-compose package as of version 31, so it is possible to install this tool on Fedora using the DNF package manager. All three methods are described in the sections below.

Note: If you have a Podman version older than 3.1.0, install the older Podman Compose 0.1.x legacy branch.

Install Podman Compose with pip

To install Podman Compose with pip, first update pip packages to the latest version:

sudo -H pip3 install --upgrade pip
Updating pip packages.

Install the latest stable version of Podman Compose:

pip3 install podman-compose

The command installs Podman Compose for all users.

Installing podman-compose with pip3.

To install for the current user only, add the --user flag:

pip3 install podman-compose --user

The latest development version of Podman Compose is available on GitHub. Install it with the following command:

sudo pip3 install https://github.com/containers/podman-compose/archive/devel.tar.gz

The output confirms the installation's success.

Installing the latest development version of podman-compose with pip3.

Execute the above-mentioned command without sudo if you wish to limit the installation of the Podman Compose development version to the current user only.

Install Podman Compose with Python Script

Install the latest Podman Compose development version by downloading the precompiled Python script. The script is available on the project's GitHub page:

sudo curl -o /usr/local/bin/podman-compose https://raw.githubusercontent.com/containers/podman-compose/devel/podman_compose.py

The curl command downloads the file and places it in the /usr/local/bin directory.

Installing the latest development version of podman-compose using the Python script.

Make the file executable by typing:

chmod +x /usr/local/bin/podman-compose

If you prefer to install Podman Compose inside your user home directory, use the same curl syntax, but change the install location:

curl -o ~/.local/bin/podman-compose https://raw.githubusercontent.com/containers/podman-compose/devel/podman_compose.py

When the download completes, assign executable permissions to the file:

chmod +x ~/.local/bin/podman-compose

Install Podman Compose on Fedora 31 and Newer

If you use Fedora 31 or a newer version of this OS, install Podman Compose directly from Fedora repositories. Use the DNF package manager:

sudo dnf install podman-compose

How to Use Podman Compose?

Using Podman Compose to deploy an app features a process similar to deploying with Docker Compose. The process involves creating a compose.yml file with instructions for Podman on how to execute the app deployment.

Below is an example of using Podman Compose to deploy a Plex media server instance.

1. Create a directory for the compose.yml file and go to that directory.

mkdir plex-test && cd plex-test

2. Use a text editor to create compose.yml.

nano compose.yml

3. Define the deployment in the file. The example below provides the necessary configuration for a Plex server:

    image: docker.io/linuxserver/plex
    container_name: plex
    network_mode: host
      - VERSION=podman
    restart: always
      - ${PLEX_MEDIA_PATH}:/media/

The services.plex.image field contains a link to the Plex image on Docker Hub. The file also defines the container name and environment variables and creates volumes for persistent data storage.

Save and exit the file when you finish editing it.

4. Issue the following command in the directory containing the compose.yml file:

podman-compose up

When the user issues the podman-compose up command, Podman Compose performs a series of tasks:

  • Creates a pod with the name corresponding to the name of the current directory.
  • Checks if the volumes specified in compose.yml exist and creates the missing volumes.
  • Creates a container for each service defined in compose.yml.
  • Adds the containers to the pod.

When the process completes, Plex displays a message containing the address for accessing the web UI.

The Plex startup message containing the address for accessing the web UI.

Keep Plex running in the terminal window.

In another terminal window, check the deployment by listing the pods running on the system:

podman pod ls

The list shows the pod plex-test pod. Inside the pod is a single container running the Plex service:

Listing available pods in Podman.

Use a browser to visit the address from the Plex start-up message:


The browser redirects you to the Plex sign-in page.

The Plex sign in screen in Firefox.

Note: Our BMC server instances allow you to optimize your containerized workload deployments by choosing the compute, memory, and network resources that fit the need of your project.

Check Running Containers

Type the command below to get a list of containers created by Podman Compose:

podman ps

The output shows a running container named plex. The name is defined in compose.yml.

Listing running containers in Podman.

Stop Containers

The standard method for stopping containers in Podman involves the podman stop command:

podman stop [container-id]
Stoping a container in Podman.

However, sometimes the number of Podman Compose containers is too large to stop manually. The following command stops all the containers associated with the specific Podman Compose deployment:

podman-compose down

The output shows that Podman Compose stops and removes the deployed containers. The pod containing those containers is also removed.

The output of the podman-compose down command.

Stop and Remove Pods

You can also manually stop and remove pods created by Podman Compose. To stop a pod, type:

podman pod stop [pod-name-or-id]

The output confirms the pod's deletion by showing the entire pod ID.

Stopping a pod in Podman.

The Plex server stops and exits to the command prompt.

The Plex server exiting to the command prompt.

Remove the stopped pods with the following podman pod command:

podman pod rm [pod-name-or-id]
Removing a pod in Podman.

Note: For a more comprehensive guide through the Podman commands, read our Podman Tutorial.


This tutorial showed you how to use Podman Compose to deploy an app on your system.

The article included multiple methods for Podman Compose installation, alongside the instructions for container management.

Was this article helpful?
Marko Aleksic
Marko Aleksić is a Technical Writer at phoenixNAP. His innate curiosity regarding all things IT, combined with over a decade long background in writing, teaching and working in IT-related fields, led him to technical writing, where he has an opportunity to employ his skills and make technology less daunting to everyone.
Next you should read
What is Podman? - Everything You Need to Know
March 24, 2022

For years, Docker has been the most widely used containerization solution. This article will introduce you to Podman...
Read more
Install Podman on Ubuntu
April 12, 2022

Podman was developed by RedHat, but it is supported by other Linux distributions as well. In this tutorial, you will learn to install and use Podman on Ubuntu.
Read more
How to Install Podman on macOS
March 17, 2022

Podman is an open-source project that has recently become popular as an alternative to Docker. Learn how to install Podman on macOS....
Read more
Podman vs Docker: Everything You Need to Know
December 12, 2023

This article will compare two container management engines - Docker and Podman. It will also help you...
Read more