Podman Tutorial - Basics for Beginners

March 31, 2022


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.

Podman tutorial, basics for beginners.


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:

attach Attach to a running container using its name or ID.
auto-update Use the container auto-update policy to update containers.
build Use Containerfiles instructions to build an image.
commit Create a new image reflecting changes made to a container.
container Manage Podman containers.
cp Copy files/directories from a container to the local filesystem and vice versa.
create Create a container without starting it.
diff Display changes made to a container or an image.
events Display podman events.
exec Execute a process inside a running container.
export Create a tar archive containing container’s filesystem contents.
generate Create structured output based on a container, volume, or pod.
healthcheck Manage container healthchecks.
history Show image history.
image Manage images.
images List images available in local storage.
import Import a filesystem image tarball.
info Show podman system info.
init Initialize containers.
inspect Show container or image configuration.
kill Kill containers.
load Load an image available in the container archive.
login Container registry login.
logout Log out of a container registry.
logs View container logs.
machine Manage the Podman VM.
manifest Create and manage manifest lists and image indexes.
mount Mount the root filesystem of a container or list currently mounted containers.
network Manage Podman networks.
pause Pause container processes.
play Play a container, volume, or pod.
pod Manage Podman pods.
port List port mappings or list a container-specific mapping for the container.
ps List running containers.
pull Copy an image from a registry to local storage.
push Push an image from a local machine to a specified destination.
rename Rename a container.
restart Restart a container.
rm Remove a container.
rmi Remove an image from local storage.
run Run a command in a container.
save Save image to a local file.
search Look for an image in a registry.
secret Manipulate secrets.
start Start a container.
stats Display resource usage statistics.
stop Stop a container.
system Manage the Podman systems.
tag Assign a name to a local image.
top Show the processes running in a container.
unmount Unmount root filesystem of a container.
unpause Unpause container processes.
unshare Launch a process in a new user namespace.
untag Remove tags from a local image.
version View the version information.
volume Manage container volumes.
wait Wait for a container to stop.

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
The output of the podman help command.

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

The output of the man podman 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
Limiting the number of search results in Podman.

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]
Inspecting an image with Podman.

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]
Inspecting an image using the format option.

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:

Pulling an image from an online registry in Podman.

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.

Pulling and running an image in Podman.

Viewing Images

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

podman images
Viewing locally available images in Podman.

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
Filtering locally available images in Podman.

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.

Building an image in Podman.

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.

Removing an image in Podman.

Podman Containers

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

Note: Podman is a native Linux tool and works best on Linux. Bare Metal Cloud servers offer automated deployment of Ubuntu, CentOS and Debian and are optimized for production environments.

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.

Running a container in the foreground.

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.

Running a container in the background.

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.

Attaching to a container in Podman.

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.

Listing running containers in Podman.

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.

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

The ID of the stopped container is shown.

Stopping a container in Podman.

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.

Naming a container.

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.

Removing a container.

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

podman rm -f [container-name-or-id]
Removing a running or unusable container with the rm -f command.

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]
Removing multiple containers with the rm command.

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.

Listing pods available on the system.

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.

Creating an empty pod.

Note: An empty pod consists of a single infra container whose purpose is keeping the pod alive and maintaining the namespaces associated with the 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:

Adding a container to a pod.

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:

Creating a pod with podman run.

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

Listing available pods,

Starting, Stopping, and Deleting Pods

Start a pod using the following command:

podman pod start [pod-name-or-id]
Starting a pod in Podman.

To stop a pod, run:

podman pod stop [pod-name-or-id]
Stopping a pod in Podman.

To remove a stopped pod and its container, use:

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

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

podman pod rm -f [pod-name-or-id]
Removing the pod using the rm -f command.

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]
Removing multiple pods with the pod rm command.

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:

Cannot expose privileged port 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.

The contents of the registries.conf file.

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.


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.

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

As one of the most efficient virtualization methods available, containerization quickly gained traction...
Read more
What is Container Orchestration? Benefits & How It Works
March 31, 2022

Container orchestration refers to a process that deals with managing the lifecycles of...
Read more
What is Docker?
January 17, 2024

Docker is one of the most popular container-based platforms attracting the attention of many development teams. More and more companies are switching to Docker due to...
Read more
How to Install Podman on macOS
March 17, 2022

For most developers and DevOps professionals, Docker is a platform synonymous with app containerization.
Read more