This tutorial explains how to get started with Podman in Linux operating systems. By the end of this Podman tutorial, you will learn Podman basics, such as how to search and download images, create a new container from the image, run a container, remove a container, and build your own image from the container and more.
Before we get started with Podman, make sure you have installed Podman on your Linux machine.
Table of Contents
Get Started With Podman
Podman provides a command-line interface (CLI) similar to the Docker container engine. In fact, Podman aims to be a drop-in replacement for docker client provided by Docker.
Podman and Docker commands are almost same. You can simply replace
podman in most docker commands. For example, the
docker run command becomes
podman run and
docker build becomes
podman build and so on.
You can even create a
docker alias for
podman like below:
$ alias docker=podman
From now on, you can use both
podman commands at the same time. For example, if you run
docker ps, it will automatically execute
podman ps command. Transitioning from Docker to Podman has became much easier!
1. Getting Podman help
The first thing you probably want to do after installing any application is to look into their help section.
To view the Podman help manual along with the ist of available sub-commands and general options, run:
$ podman --help
To learn the usage of any sub-command, for example
attach, simply do:
$ podman attach --help
2. Search images
Let us search for Alpine Linux images using command:
$ podman search alpine
As you can see, Podman lists Alpine images from both Docker hub and Quay.
When you download images, you can choose from where you want to get them.
Similarly, you can search images based on Arch Linux like below:
$ podman search archlinux
Docker hub and Quay has lots of images of different types. Be it an application, or operating system, you will find the pre-built container images from these registries.
3. Download images
For the purpose of this guide, I will download Redhat 8 Universal base image (UBI).
To download the Redhat image with Podman, run:
$ podman pull redhat/ubi8
You will be asked to choose a container registry to download from. I chose Docker hub. You will see a small arrow in-front of the selected registry.
? Please select an image: registry.fedoraproject.org/redhat/ubi8:latest registry.access.redhat.com/redhat/ubi8:latest ▸ docker.io/redhat/ubi8:latest quay.io/redhat/ubi8:latest
The container image will be downloaded from the chosen registry.
✔ docker.io/redhat/ubi8:latest Trying to pull docker.io/redhat/ubi8:latest... Getting image source signatures Copying blob a50df8fd88fe done Copying blob 1cadda38f72d done Copying config 0ced1c7c9b done Writing manifest to image destination Storing signatures 0ced1c7c9b23d0e107c7b15d5a0017abbbcf7e64e49a4c9f9efa1b9589ca8b68
You can download and run different type of images regardless of the distribution type you use. For example, you can download and use Alpine images on a Fedora host and vice versa.
$ podman pull alpine
You can even download a specific version of an image. The following command downloads Ubuntu version 20.04 image:
$ podman pull ubuntu:20.04
Since we use Podman as non-root user, all container images are stored under the user's home directory, i.e
$HOME/.local/share/containers/storage, instead of
$ ls ~/.local/share/containers/storage/ cache libpod mounts overlay overlay-containers overlay-images overlay-layers storage.lock tmp userns.lock
4. View images
To view the list of locally downloaded images, run:
$ podman images
REPOSITORY TAG IMAGE ID CREATED SIZE docker.io/library/ubuntu 20.04 1318b700e415 7 days ago 75.2 MB docker.io/redhat/ubi8 latest 0ced1c7c9b23 13 days ago 234 MB docker.io/library/alpine latest d4ff818577bc 6 weeks ago 5.87 MB
As you can see, the above output lists the name of repository where we downloaded the images, image tag, image id, when the image is created and the image size.
For those wondering, the TAG refers to a particular snapshot of the Ubuntu image (E.g. 20.04 and latest). TAG is just an additional name to a local image. The IMAGE ID (E.g. 1318b700e415 ) is the unique identifier of Ubuntu image.
5. Run containers
A container can be started either using the image tag or image id.
Let us start a new container with Redhat UBI image using its tag:
$ podman run -it ubi8:latest
This command creates a Redhat 8 container using
ubi8:latest image and connects the container to the terminal so that you can interact with it.
-i: Allows us to make an interactive connection by grabbing the standard in (STDIN) of the container.
-t: Assigns a new Pseudo Terminal inside the Redhat 8 container.
ubi8:latest: Redhat 8 container with TAG "latest".
After starting the container, you'll be landed automatically in the Container's shell (Command prompt):
Did you notice the number
607a288c810d in the above output? It is the Container ID.
Heads Up: Please note that Container ID and Docker image ID are different.
You can start playing with your Container now.
To go back to your host's Terminal without exiting the Container, press
CTRL+p followed by
Now you will be detached from the container and returned back to the host machine's console. The container will still be running in the background.
To exit from the container, simply type
exit from the Container's console and press ENTER key:
This command will shutdown the running Container.
If you want to run a container with the IMAGE ID, simply replace the image TAG (ubi8:latest) with image ID (0ced1c7c9b23) in the previous command:
$ podman run -it 0ced1c7c9b23
This will start the Redhat 8 container.
6. Run containers in the background
You can also run Containers in the background detached.
To run a Container in detached mode, we use
$ podman run -it -d ubi8:latest
When we run the Container in detached mode, Podman will display the Container ID in the standard output.
Let us verify the running containers using command:
$ podman ps
Now the Container is running in the background.
You can attach to it as described in the following section.
7. Attach and detach from containers
As stated in the previous section, you can safely detach from a running Container by pressing
CTRL+p followed by
CTRL+q. This will let you go back to the host's Terminal.
To attach to the Container again, first find the running Container ID or its name using
podman ps command:
$ podman ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
607a288c810d docker.io/redhat/ubi8:latest /bin/bash 2 hours ago Up 2 hours ago cool_cannon
607a288c810d is the Container ID.
And then simply type
podman attach command followed by the Container ID like below:
$ podman attach 607a288c810d
You can also attach to it using the Container name like below:
$ podman attach cool_cannon
To detach from the Container, simply press
8. View running containers
To find or list the running Containers, type:
$ podman ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES e783c0202b7d docker.io/library/alpine:latest /bin/sh 37 seconds ago Up 38 seconds ago optimistic_murdock
This will only list the running containers. If you want to list both running and stopped containers, use
$ podman ps -a
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 56c20497cbcd docker.io/redhat/ubi8:latest /bin/bash 3 hours ago Exited (0) 3 hours ago wizardly_albattani d23672b15cff docker.io/redhat/ubi8:latest /bin/bash 3 hours ago Exited (0) 3 hours ago nifty_merkle 89b2c038e1ba docker.io/redhat/ubi8:latest /bin/bash 3 hours ago Exited (0) 2 hours ago xenodochial_euler 607a288c810d docker.io/redhat/ubi8:latest /bin/bash 2 hours ago Exited (0) About a minute ago cool_cannon e783c0202b7d docker.io/library/alpine:latest /bin/sh 43 seconds ago Up 43 seconds ago optimistic_murdock
9. Automatically delete container after closing it
You may want to test a Container and simply delete it as soon as you're done with the Container. If so, you can automatically delete the Container after closing it by using
$ podman run -it --rm ubi8:latest
Once you exit from the Container, it will be automatically deleted.
10. Start and stop containers
As stated already, we can create multiple Containers using the same image. This is one of the biggest advantage of Containers compared to physical or virtual machines.
To create multiple new Containers, we can use the
podman run command as described in "5. Run containers" section.
To start (power on) an existing Container, we simply do:
$ podman start <container_name>
Similarly, we can stop (power off) a running command with command:
$ podman stop <container_name>
Let me show you an example, so you will understand better.
First, find the list of all Containers:
$ podman ps -a CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 56c20497cbcd docker.io/redhat/ubi8:latest /bin/bash 2 days ago Exited (0) 2 days ago wizardly_albattani d23672b15cff docker.io/redhat/ubi8:latest /bin/bash 2 days ago Exited (0) 2 days ago nifty_merkle 89b2c038e1ba docker.io/redhat/ubi8:latest /bin/bash 2 days ago Exited (0) 2 days ago xenodochial_euler 607a288c810d docker.io/redhat/ubi8:latest /bin/bash 2 days ago Exited (0) 2 days ago cool_cannon e783c0202b7d docker.io/library/alpine:latest /bin/sh 2 days ago Exited (0) 2 days ago optimistic_murdock
The name of the Containers are shown in the NAMES section (last column) of the above output.
I am going to start the Container named
wizardly_albattani using command:
$ podman start wizardly_albattani
Let us check if it is started:
$ podman ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 56c20497cbcd docker.io/redhat/ubi8:latest /bin/bash 2 days ago Up 7 seconds ago wizardly_albattani
Yes, it was up 7 seconds ago.
To stop the Container, simply do:
$ podman stop wizardly_albattani
11. Assign name to containers
If you closely look into the output of previous commands, Podman assigns random names each time when you start a container. If you don't name your Containers, Podman will name them for you automatically.
Have a look at the following screenshot. I have started the same Container with the same image twice. After I exit the container and restart it at the second time, it gets new name even if I used the same image.
The containers gets new name every time after we close and start them each time.
You can, however, assign a static name to the containers with
--name flag like below:
$ podman run -it -d --name ostechnix_redhat ubi8:latest
The above command will create run a new Container in detached mode and name it as
To view list of the running Containers, we do:
$ podman ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
6fa78116dcb7 docker.io/redhat/ubi8:latest /bin/bash 4 seconds ago Up 5 seconds ago ostechnix_redhat
Did you notice the name of the Container? We have given a custom name (i.e.
ostechnix_redhat) to the Container.
12. Build custom images
Podman is not just for downloading and running Containers from pre-configured Images. Ye can also build your custom images from existing images.
First, start an existing Container or run a new one.
I am going to create a new Ubuntu container:
$ podman run -it 1318b700e415
Now you're inside the Container.
Just install, upgrade or remove any applications in the Container.
For the purpose of this guide, I will install Apache web server:
root@b871b0fd5810:/# apt update
root@b871b0fd5810:/# apt install apache2 -y
root@b871b0fd5810:/# service apache2 start
Once you're done, detach from the Container and return back to the host's terminal by pressing
Please note that the Container is still running in the background!
Now, build the Image from the existing Container using command:
$ podman commit b871b0fd5810 ostechnix/ubuntu_apache
b871b0fd5810- Ubuntu container ID.
ostechnix– Name of the user who created the container.
ubuntu_apache– Name of the image created by user ostechnix.
Now check if the new image is created by listing the available images:
$ podman images
REPOSITORY TAG IMAGE ID CREATED SIZE localhost/ostechnix/ubuntu_apache latest 6c9b2fb66400 25 seconds ago 222 MB docker.io/library/ubuntu 20.04 1318b700e415 10 days ago 75.2 MB docker.io/redhat/ubi8 latest 0ced1c7c9b23 2 weeks ago 234 MB docker.io/library/alpine latest d4ff818577bc 7 weeks ago 5.87 MB
As you see in the above output, a new image called
ubuntu_apache is created.
Let us start the a new Container with this image:
$ podman run -it --rm --name apache_webserver -p 8080:80 localhost/ostechnix/ubuntu_apache
Here, I am running Container with newly created Image in the earlier step. I am also mapping the local port
8080 on the local system to port
80 inside of the container.
Once the Container is started, make sure the Apache web server is started using command:
root@d0f60f4dad85:/# service apache2 start
Now, open your browser in your host system and naviagate to
http://localhost:8080 to verify if Apache web server is running in the Container.
13. View containers logs
To view everything you did inside your Container, you can simply check the logs of the Container using command:
$ podman logs apache_webserver
14. Remove containers
Make sure the Containers is stopped:
$ podman stop ostechnix_redhat
After stopping the Container, delete it using command:
$ podman rm ostechnix_redhat
Similarly, delete all Containers one by one as shown above.
Deleting multiple containers one by one can be a tedious task if you have large number of Containers. Instead of deleting one after another, you can delete all at once. Just be careful! There is no way to recover deleted Containers!
To delete all stopped containers in one go, just run:
$ podman container prune
"Y" to confirm and hit
ENTER key to delete the containers.
WARNING! This will remove all non running containers. Are you sure you want to continue? [y/N] y 2124a1fbc85a6be7d516e747723129bd7bb9c39d3a54951c9a81407d30ded1ab 54884f3375947026d4e87b99cb3a09e114c89120b101f5c8c1e614aca963975c 56c20497cbcdd9599c2fa729277ecf679ac29f79a0b06af3ae1a135726465ba7 607a288c810d2e605d9ba7590f8f7558ef5f96e87897a1cdde471ae9a74b36ad 69bbd87b44cb6c9a582749f4ad010b6b273e65f9fe424058fdc0bc55b188d7e4 89b2c038e1baf6ac59f0da8e43a7efedc7ba73a18ed8d704c879ffdbc7eb7f28 a4846b2454b1eb63e6d532b0f7ef4a05ca19f965caf9cd0d4a2ce17131a05e29 aa14879baf0919323730539dd949231d5bb89ca4207dd36c02a741316e6d0f18 b871b0fd5810f55e75bdd480d5fb34b09b0e293604f88896002a9368a607bf7e d23672b15cffc0a774227dc6b457a8bff5347073a112f6729d63ddf400f19dc7 e783c0202b7d7a6664e731feeff4bdb57a79df79080046ed2b728df4bce789d2 ebfd6210a6beedce43af0c41296e329d416128752ab603abd44c73117bf5dfd0
15. Remove images
You can delete the Images that are no longer required!
List all downloaded images with command:
$ podman images
REPOSITORY TAG IMAGE ID CREATED SIZE localhost/ostechnix/ubuntu_apache latest 6c9b2fb66400 37 minutes ago 222 MB docker.io/library/ubuntu 20.04 1318b700e415 10 days ago 75.2 MB docker.io/redhat/ubi8 latest 0ced1c7c9b23 2 weeks ago 234 MB docker.io/library/alpine latest d4ff818577bc 7 weeks ago 5.87 MB
Now, delete an image either using its Image ID or Name, like below:
$ podman rmi 6c9b2fb66400
Untagged: localhost/ostechnix/ubuntu_apache:latest Deleted: 6c9b2fb66400138738ad12643d8461fbbb859f33d3be3c35181bb9ee9b11748d
Similarly, delete all other non-used images,
Heads Up: You can't delete an Image that is currently being used by either running or stopped Containers.
In this comprehensive Podman tutorial, we provided 15 practical examples on how to get started with Podman in Linux. If you are a developer, learning Podman is very important to advance your career. Learn to use Podman thoroughly. It's worth your time!