Chapter 2. Working with container images

Using podman, you can run, start, stop, investigate, and remove container images.

2.1. Searching for container images

The podman search command lets you search selected container registries for images.


You can also search for images in the Red Hat Container Registry. The Red Hat Container Registry includes the image description, contents, health index, and other information.

You can find the list of registries in the configuration file registries.conf:

registries = ['', '', '']

registries = []

registries = []
  • By default, the podman search command searches for container images from registries listed in section [] in the given order. In this case, podman search command looks for the requested image in, and in this order.
  • The [registries.insecure] section adds the registries that do not use TLS (an insecure registry).
  • The [registries.block] section disallows the access to the registry from your local system.

As a root user, you can edit the /etc/containers/registries.conf file to change the default, system-wide search settings.

As a regular (rootless) user of podman, you can create your own registries.conf file in your home directory ($HOME/.config/containers/registries.conf) to override the system-wide settings.

Make sure that you follow the conditions when configuring container registries:

  • Each registry must be surrounded by single quotes.
  • If there are multiple registries set for the registries = value, you must separate those registries by commas.
  • You can identify registries by either IP address or hostname.
  • If the registry uses a non-standard port - other than TCP ports 443 for secure and 80 for insecure, enter that port number with the registry name. For example:
  • The system searches for registries in the order in which they appear in the list of the registries.conf file.

Some podman search command examples follow. The first example illustrates the unsuccessful search of all images from The forwardslash at the end means to search the whole registry for all images accessible to you:

# podman search
ERRO[0000] error searching registry "": couldn't search registry "":
unable to retrieve auth token: invalid username/password

To search registry, log in first:

# podman login
Username: johndoe
Password: ***********
Login Succeeded!
# podman search
INDEX     NAME                                       DESCRIPTION   STARS   OFFICIAL   AUTOMATED                                      0                                   0                                 0                                 0                              0

Search all available registries for postgresql images (resulting in more than 40 images found):

# podman search postgresql-10
INDEX       NAME                                            DESCRIPTION                    STARS OFFICIAL AUTOMATED          This container image ...       0    PostgreSQL is an advanced ...  0          PostgreSQL is an advanced ... 13

To limit your search for postgresql to images from, type the following command. Notice that by entering the registry and the image name, any repository in the registry can be matched:

# podman search
INDEX       NAME                                           DESCRIPTION           STARS   OFFICIAL   AUTOMATED         This container image ...  0   PostgreSQL is an  ...     0

To get longer descriptions for each container image, add --no-trunc to the command:

# podman search --no-trunc
                   This container image provides a containerized
                   packaging of the PostgreSQL postgres daemon and
                   client application. The postgres server daemon
                   accepts connections from clients and provides
                   access to content from PostgreSQL databases on
                   behalf of the clients.   0

To access insecure registries, add the fully-qualified name of the registry to the [registries.insecure] section of the /etc/containers/registries.conf file. For example:

registries = ['']

registries = ['']

Then, search for myimage images:

# podman search
INDEX      NAME  DESCRIPTION                                       STARS  OFFICIAL  AUTOMATED
   The myimage container executes the ...   0

Now you can pull myimage image:

# podman pull

2.2. Pulling images from registries

To get container images from a remote registry (such as Red Hat’s own container registry) and add them to your local system, use the podman pull command:

# podman pull <registry>[:<port>]/[<namespace>/]<name>:<tag>

The <registry> is a host that provides a container registry service on TCP <port>. Together, <namespace> and <name> identify a particular image controlled by <namespace> at that registry. The <tag> is an additional name to locally-stored image, the default tag is latest. Always use fully qualified image names including: registry, namespace, image name and tag. When using short names, there is always an inherent risk of spoofing. Add registries that are trusted, that is registries which do not allow unknown or anonymous users to create accounts with arbitrary names.

Some registries also support raw <name>; for those, <namespace> is optional. When it is included, however, the additional level of hierarchy that <namespace> provides is useful to distinguish between images with the same <name>. For example:

NamespaceExamples (<namespace>/<name>)


redhat/kubernetes, google/kubernetes

login (user name)

alice/application, bob/application


devel/database, test/database, prod/database

The registries that Red Hat provides are (requiring authentication), (requires no authentication), and (holds Red Hat Partner Connect program images). For details on the transition to, see Red Hat Container Registry Authentication . Before you can pull containers from, you need to authenticate. For example:

# podman login
Username: myusername
Password: ************
Login Succeeded!

Use the pull option to pull an image from a remote registry. To pull the rhel base image and rsyslog logging image from the Red Hat registry, type:

# podman pull
# podman pull

An image is identified by a registry name (, a namespace name (ubi8) and the image name (ubi). You could also add a tag (which defaults to :latest if not entered). The repository name ubi, when passed to the podman pull command without the name of a registry preceding it, is ambiguous and could result in the retrieval of an image that originates from an untrusted registry. If there are multiple versions of the same image, adding a tag, such as latest to form a name such as ubi8/ubi:latest, lets you choose the image more explicitly.

To see the images that resulted from the above podman pull command, along with any other images on your system, type podman images:

REPOSITORY                        TAG    IMAGE ID      CREATED     SIZE       latest eb205f07ce7d  2 weeks ago 214MB  latest 85cfba5cd49c  2 weeks ago 234MB

The ubi and rsyslog images are now available on your local system for you to work with.

2.3. Investigating images

Using podman images you can see which images have been pulled to your local system. To look at the metadata associated with an image, use podman inspect.

2.3.1. Listing images

To see which images have been pulled to your local system and are available to use, type:

# podman images
REPOSITORY                               TAG      IMAGE ID     CREATED      VIRTUAL SIZE   latest   b3d6ce4e0043 2 days ago   234MB         latest   779a05997856 2 days ago   225MB              latest   a80dad1c1953 3 days ago   210MB

2.3.2. Inspecting local images

After you pull an image to your local system and before you run it, it is a good idea to investigate that image. Reasons for investigating an image before you run it include:

  • Understanding what the image does
  • Checking what software is inside the image

The podman inspect command displays basic information about what an image does. You also have the option of mounting the image to your host system and using tools from the host to investigate what’s in the image. Here is an example of investigating what a container image does before you run it:

  1. Inspect an image: Run podman inspect to see what command is executed when you run the container image, as well as other information. Here are examples of examining the ubi8/ubi and rhel8/rsyslog container images (with only snippets of information shown here):

    # podman pull
    # podman inspect | less
       "Cmd": [
       "Labels": {
           "License": "GPLv3",
           "architecture": "x86_64",
           "authoritative-source-url": "",
           "build-date": "2018-10-24T16:46:08.916139",
           "": "",
           "com.redhat.component": "rhel-server-container",
           "description": "The Red Hat Enterprise Linux Base image is designed to be a fully supported...
    # podman pull
    # podman inspect
       "Cmd": [
       "Labels": {
         "License": "GPLv3",
         "architecture": "x86_64",
         "install": "podman run --rm --privileged -v /:/host -e HOST=/host -e IMAGE=IMAGE -e NAME=NAME IMAGE /bin/",
         "run": "podman run -d --privileged --name NAME --net=host --pid=host -v /etc/pki/rsyslog:/etc/pki/rsyslog -v /etc/rsyslog.conf:/etc/rsyslog.conf -v /etc/sysconfig/rsyslog:/etc/sysconfig/rsyslog -v /etc/rsyslog.d:/etc/rsyslog.d -v /var/log:/var/log -v /var/lib/rsyslog:/var/lib/rsyslog -v /run:/run -v /etc/machine-id:/etc/machine-id -v /etc/localtime:/etc/localtime -e IMAGE=IMAGE -e NAME=NAME --restart=always IMAGE /bin/",
         "summary": "A containerized version of the rsyslog utility

    The ubi8/ubi container will execute the bash shell, if no other argument is given when you start it with podman run. If an Entrypoint were set, its value would be used instead of the Cmd value (and the value of Cmd would be used as an argument to the Entrypoint command).

    In the second example, the rhel8/rsyslog container image has built-in install and run labels. Those labels give an indication of how the container is meant to be set up on the system (install) and executed (run).

  2. Mount a container: Using the podman command, mount an active container to further investigate its contents. This example runs and lists a running rsyslog container, then displays the mount point from which you can examine the contents of its file system:

    # podman run -d
    # podman ps
    1cc92aea398d ...rsyslog:latest /bin/ 37 minutes ago Up 1 day ago      myrsyslog
    # podman mount 1cc92aea398d
    # ls /var/lib/containers/storage/overlay/65881e78*/merged
    bin  boot  dev  etc  home  lib  lib64  media  mnt  opt  proc  root  run  sbin  srv  sys  tmp  usr  var

    After the podman mount, the contents of the container are accessible from the listed directory on the host. Use ls to explore the contents of the image.

  3. Check the image’s package list: To check the packages installed in the container, tell the rpm command to examine the packages installed on the container’s mount point:

    # rpm -qa --root=/var/lib/containers/storage/overlay/65881e78.../merged

2.3.3. Inspecting remote images

To inspect a container image before you pull it to your system, you can use the skopeo inspect command. With skopeo inspect, you can display information about an image that resides in a remote container registry.

The following command inspects the ubi8-init image from the Red Hat registry:

# skopeo inspect docker://
    "Name": "",
    "Digest": "sha256:53dfe24...",
    "RepoTags": [
    "Created": "2019-05-13T20:50:11.437931Z",
    "DockerVersion": "1.13.1",
    "Labels": {
        "architecture": "x86_64",
        "authoritative-source-url": "",
        "build-date": "2019-05-13T20:49:44.207967",
        "": "",
        "com.redhat.component": "ubi8-init-container",
        "description": "The Red Hat Enterprise Linux Init image is designed to be...

2.4. Tagging images

You can add names to images to make it more intuitive to understand what they contain. Tagging images can also be used to identify the target registry for which the image is intended. Using the podman tag command, you essentially add an alias to the image that can consist of several parts. Those parts can include:


You can add just NAME if you like. For example:

# podman tag 474ff279782b myrhel8

In the previous example, the rhel8 image had an image ID of 474ff279782b. Using podman tag, the name myrhel8 now also is attached to the image ID. So you could run this container by name (rhel8 or myrhel8) or by image ID. Notice that without adding a :tag to the name, it was assigned :latest as the tag. You could have set the tag to 8.0 as follows:

# podman tag 474ff279782b myrhel8:8.0

To the beginning of the name, you can optionally add a user name and/or a registry name. The user name is actually the repository on that relates to the user account that owns the repository. Tagging an image with a registry name was shown in the "Tagging Images" section earlier in this document. Here’s an example of adding a user name:

# podman tag 474ff279782b jsmith/myrhel8
# podman images | grep 474ff279782b
rhel8           latest  474ff279782b  7 days ago  139.6 MB
myrhel8         latest  474ff279782b  7 months ago  139.6 MB
myrhel8         7.1     474ff279782b  7 months ago  139.6 MB
jsmith/myrhel8  latest  474ff279782b  7 months ago  139.6 MB

Above, you can see all the image names assigned to the single image ID.

2.5. Saving and loading images

If you want to save a container image you have stored locally, you can use podman save to save the image to an archive file or directory and restore it later to another container environment. The archive you save can be in any of several different container image formats: docker-archive, oci-archive, oci-dir (directory with oci manifext type), or docker-dir (directory with v2s2 manifest type). After you save an image, you can store it or send it to someone else, then load the image later to reuse it. Here is an example of saving an image as a tarball in the default docker-archive format:

# podman save -o myrsyslog.tar
# file myrsyslog.tar
myrsyslog.tar: POSIX tar archive

The myrsyslog.tar file is now stored in your current directory. Later, when you are ready to reuse the tarball as a container image, you can import it to another podman environment as follows:

# podman load -i myrsyslog.tar
# podman images
REPOSITORY                       TAG    IMAGE ID      CREATED     SIZE latest 1f5313131bf0  7 weeks ago 235 MB

Instead of using save and load to store and reload an image, you can make a copy of a container instead, using podman export and podman import.

2.6. Removing Images

To see a list of images that are on your system, run the podman images command. To remove images you no longer need, use the podman rmi command, with the image ID or name as an option. (You must stop any containers run from an image before you can remove the image.) Here is an example:

# podman rmi ubi8-init

You can remove multiple images on the same command line:

# podman rmi support-tools

If you want to clear out all your images, you could use a command like the following to remove all images from your local registry (make sure you mean it before you do this!):

# podman rmi -a

To remove images that have multiple names (tags) associated with them, you need to add the force option to remove them. For example:

# podman rmi -a
A container associated with containers/storage, i.e. via Buildah, CRI-O, etc., may be associated with this image: 1de7d7b3f531

# podman rmi -f 1de7d7b3f531