Podman Tutorial – Basics for Beginners

Introduction

Podman is a container engine for running and managing OCI containers on Linux. RedHat develops it as a direct alternative to Docker, the famous container management platform that started it all.

This tutorial will help you understand how Podman works by explaining its command syntax, and providing real-life examples of how to use Podman commands.

Prerequisites

• Access to a command line/terminal window.
• Podman installed and configured (see How to Install Podman on macOS or How to Install Podman on Ubuntu).

Podman Commands

Podman has a very similar command syntax to Docker. The main podman command is followed by Podman management commands and options:

podman [command] [options]

Below is a table containing all Podman commands:

Podman Tutorial

Although Podman is primarily a container engine – it is designed to create and run OCI containers, users can also use podman commands to manage container images.

The following sections explain how to use Podman to create and manipulate images, containers, and pods.

Viewing Podman Help Manual

You can reference Podman documentation quickly using the command line. To view available podman commands in your terminal, type:

podman help

To see the full Podman manual, use the man command:

Podman Images

Image building and management in Podman is performed with Buildah, an image-building tool that uses a lower-level coreutils interface. When a user executes a podman command related to images, Podman calls Buildah to perform the action.

The following sections demonstrate some important image management commands.

Searching Images

Search registries for available images using the search command.

podman search [search-term]

Limit the number of results with the --limit option. For example, to produce three results for the “centos” search term, type:

podman search --limit 3 centos

Inspect Image

Prior to pulling a Podman image, it is good practice to inspect it. Use the podman inspect command and the system outputs image metadata, such as file size, architecture, OS, etc.

podman inspect [repository or image ID]

Use the --format option with the podman inspect command to get specific metadata. In the example below, the command returns just the image’s description:

podman inspect --format=’{{.Labels.description}}’ [image ID]

Downloading Images

Pulling images from online repositories is performed using the podman pull command. The syntax is:

podman pull [registry/image]

The example illustrates pulling an image from the fedoraproject.org registry:

Running Images

Run Podman images with podman run:

podman run [image]

If the image is not locally available, Podman pulls it from an online registry and then runs it as a container.

Viewing Images

The podman images sub-command is used to list locally available images:

podman images

Use options to narrow the search results. The --filter option filters the output based on the conditions you provide. For example, the following command looks for all images containing “redhat” in the name:

podman images --filter reference=redhat

Building Custom Images

To build custom images with Podman, you need a dockerfile or containerfile. These files contain instructions the Buildah tool uses to create an image.

Building files is performed with the podman build command. For example, to create an image from a directory containing the instruction script, run the following command:

podman build .

Buildah gathers the necessary file context and builds an image.

Removing Images

The podman rmi command is used to remove images from the local storage. Before removing a Podman image, make sure that all related containers have been stopped and removed.

Remove an image by using the podman rmi command followed by the image name or ID:

podman rmi [image-name-or-id]

The output confirms the image was removed.

Podman Containers

Creating and managing containers is Podman’s main function. Find some of the most common container management commands in the section below.

Running Containers

The podman run command has the same functions as docker run. The options that follow the command depend on the type of container being run. The example below illustrates running an httpd instance, using an image available in the docker.io repository:

podman run -p 8080:80/tcp docker.io/library/httpd

The command runs the container and displays its command prompt.

Exit the container prompt by pressing Ctrl + C. This command will exit the container.

Running Containers in the Background

To skip the container prompt and run the container in the background, use the following syntax:

podman run -dt -p 8080:80/tcp docker.io/library/httpd

If the container starts successfully, the output of the command displays the container’s long ID.

Attaching to Containers

Enter the container with the podman attach command:

podman attach [container-name-or-id]

The example shows attaching to a running Alpine Linux container using the container ID.

Viewing Running Containers

View currently running containers with the ps command:

podman ps

The command output shows a list containing basic information about running containers.

Automatically Deleting Containers After Closing

Use the --rm option with podman run to automatically delete a container:

podman run --rm -dt -p 8080:80/tcp alpine:latest

Starting and Stopping Containers

Use start and stop commands to start and stop existing containers.

podman start [container-id]

The output shows the container ID.

podman stop [container-id]

The ID of the stopped container is shown.

Assigning Names to Containers

You can name running containers using the option --name with the podman run command. For example, to name an Alpine Linux container, use the following command:

podman run --name AlpineTest -dt -p 8080:80/tcp alpine:latest

The image below shows that podman run was successful. The podman ps command lists running Podman containers, and the name is visible in the NAMES column.

Viewing Containers Logs

Display container logs at the time of execution with the podman logs command.

podman logs [container-name-or-id]

Use the -l flag to display the logs for the newest container.

Removing Containers

To delete a Podman container, first make sure that the container has been stopped. Then, use the podman rm command followed by the container’s name or ID.

podman rm [container-name-or-id]

The example below shows the removal of the AlpineTest container.

To remove a running or unusable container, add the -f option.

podman rm -f [container-name-or-id]

To remove multiple containers in one go, list the containers’ IDs separated with a space:

podman rm [container-1-id container-2-id container-3-id]

Podman Pods

Pods are groups of containers that share resources. Podman pods are the feature that distinguishes Podman from Docker. The next sections illustrate some of the common pod operations in Podman.

Listing Pods

Use the command below to list all pods available on the system:

podman pod ls

The list shows pod ID, name, status, time of creation, infra ID, and the number of containers it contains.

Creating Empty Pods

Create an empty pod in Podman using the following syntax:

podman pod create

The output shows the ID of the newly created pod.

Adding Containers to Pods

To add a container to a pod, use the --pod label with docker run:

podman run [options] --pod [pod-name-or-id] [image]

In the example below, an Alpine Linux container is assigned to the pod with the ID e06ed089b454:

Creating Pods With Containers

Podman can create a container and add it to a new pod in a single podman run command. The syntax includes the --pod label:

podman run [options] --pod new:[pod-name] [image]

The example below runs a container with the alpine:latest image and adds it to a new pod named AlpineTest:

The podman pod ls command output shows the new pod with two containers.

Starting, Stopping, and Deleting Pods

Start a pod using the following command:

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

To stop a pod, run:

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

To remove a stopped pod and its container, use:

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

To stop and remove running containers and then remove the pod, use the -f option:

podman pod rm -f [pod-name-or-id]

To remove multiple stopped pods with one command, list pod IDs separated with a space:

podman pod rm -f [pod1-id pod2-id pod3-id]

Potential Podman Issues and How to Troubleshoot Them

This section lists some common Podman issues and provides solutions.

Cannot Expose Privileged Port

Podman allows non-root users to run containers. However, they are limited to forwarding only to non-privileged ports. If you attempt to forward to a privileged port as a non-root user, you receive the following error:

The solution to this issue is to choose a non-privileged port or run the command using sudo.

podman search Issues

Another common problem is the podman search command returning an empty output.

This issue usually relates to the /etc/containers/registries.conf file. Open the file in a text editor:

sudo nano /etc/containers/registries.conf

Scroll to the bottom of the file and ensure that Podman has registries to search.

If you do not have any registries listed in the file, you can add the common ones, such as RedHat, Fedora, and Docker, by using the following syntax:

unqualified-search-registries=["registry.access.redhat.com", "registry.fedoraproject.org", "docker.io"]

Save the file. The podman search list should be populated with results from the registered online registries.

Error: invalid config provided

When adding containers to a pod, the following message may appear:

Error: invalid config provided: published or exposed ports must be defined when the pod is created: network cannot be configured when it is shared with a pod

This issue occurs when you attempt to add a container with ports that were not defined on pod creation. Currently, Podman does not allow this.

Conclusion

After reading this tutorial, you learned how to use Podman commands to create and manage images, containers, and pods. For a detailed comparison between Podman and Docker, read the Podman vs Docker article.