Managing Container Images with Podman

Image registries are services offering container images to download. They allow image creators and maintainers to store and distribute container images to public or private audiences. Podman searches for and downloads container images from public and private registries. Red Hat Container Catalog is the public image registry managed by Red Hat. It hosts a large set of container images, including those provided by major open source projects, such as Apache, MySQL, and Jenkins. is another public image repository sponsored by Red Hat. introduces several exciting features, such as server-side image building, fine-grained access controls, and automatic scanning of images for known vulnerabilities. While Red Hat Container Catalog images are trusted and verified, offers live images regularly updated by creators. users can create their namespaces, with fine-grained access control, and publish the images they create to that namespace. Container Catalog users rarely or
never push new images, but consume trusted images generated by the Red Hat team.

Configuring Registries in Podman
To configure registries for the podman command, you need to update the /etc/containers/registries.conf file. Edit the registries entry in the [] section, adding an entry to the values list.

Use an FQDN and port number to identify a registry. A registry that does not include a port number has a default port number of 5000. If the registry uses a different port, it must be specified. Indicate port numbers by appending a colon (:) and the port number after the FQDN.

Secure connections to a registry require a trusted certificate. To support insecure connections, add the registry name to the registries entry in [registries.insecure] section of /etc/containers/registries.conf file:


Searching for Images in Registries
The podman search command finds images by image name, user name, or description from all the registries listed in the /etc/containers/registries.conf configuration file. The syntax for the podman search command is shown below:

$ sudo podman search [OPTIONS] <term>

The following table shows some useful options available for the search subcommand:

Option Description
--limit <number> Limits the number of listed images per
--filter <filter=value> Filter output based on conditions provided. Supported filters are:
stars=<number>: Show only images with at least this number of stars.
is-automated=<true|false>: Show
only images automatically built.
is-official=<true|false>: Show only images flagged as official.
--tls-verify <true|false> Enables or disables HTTPS certificate
validation for all used registries. true

Some container image registries require access authorization. The podman login command allows username and password authentication to a registry:


Pulling Images
To pull container images from a registry, use the podman pull command:

The podman pull command uses the image name obtained from the search subcommand to pull an image from a registry. The pull subcommand allows adding the registry name to the image. This variant supports having the same image in multiple registries. For example, to pull an NGINX container from the registry, use the following command:

If the image name does not include a registry name, Podman searches for a
matching container image using the registries listed in the /etc/containers/
registries.conf configuration file. Podman search for images in registries in the same order they appear in the configuration file.

Listing Local Copies of Images

Any container image downloaded from a registry is stored locally on the same host where the podman command is executed.  Podman also stores any custom container images you build in the same local storage. By default, Podman stores container images in the /var/lib/containers/storage/overlay-images directory. Podman provides an images subcommand to list all the container images stored locally.

Image Tags
An image tag is a mechanism to support multiple releases of the same image. This feature is useful when multiple versions of the same software are provided, such as a production-ready container or the latest updates of the same software developed for community evaluation. Any Podman subcommand that requires a container image name accepts a tag parameter to differentiate
between multiple tags. If an image name does not contain a tag, then the tag value defaults to latest. For example, to pull an image with the tag 5.7 from rhscl/mysql-57-rhel7, use the following command:

To start a new container based on the rhscl/mysql-57-rhel7:5.7 image, use the following command:


Saving and Loading Images
Existing images from the Podman local storage can be saved to a .tar file using the podman save command. The generated file is not a regular TAR archive; it contains image metadata and preserves the original image layers. Using this file, Podman can recreate the original image exactly as it was.

The general syntax of the save subcommand is as follows:

Podman sends the generated image to the standard output as binary data. To avoid that, use the -o option. The following example saves the previously downloaded MySQL container image from the Red Hat Container Catalog to the mysql.tar file:

Use the .tar files generated by the save subcommand for backup purposes. To restore the container image, use the podman load command. The general syntax of the command is as follows:

For example, this command would load an image saved in a file named mysql.tar.

If the .tar file given as an argument is not a container image with metadata, the podman load command fails. To save disk space, compress the file generated by the save subcommand with Gzip using the --compress parameter. The load subcommand uses the gunzip command before importing the file to the local storage.

Deleting Images
Podman keeps any image downloaded in its local storage, even the ones currently unused by any container. However, images can become outdated, and should be subsequently replaced. Any updates to images in a registry are not automatically updated. The image must be removed and then pulled again to guarantee that the local storage has the latest version of an image.

To delete an image from the local storage, run the podman rmi command.

An image can be referenced using its name or its ID for removal purposes. Podman cannot delete images while containers are using that image. You must stop and remove all containers using that image before deleting it. To avoid this, the rmi subcommand has the --force option. This option forces the removal of
an image even if that the image is used by several containers or these containers are running.  Podman stops and removes all containers using the forcefully removed image before removing it.

To delete all images that are not used by any container, use the following command:

The command returns all the image IDs available in the local storage and passes them as parameters to the podman rmi command for removal. Images that are in use are not deleted. However, this does not prevent any unused images from being removed.

Modifying Images
Ideally, all container images should be built using a Dockerfile, in order to create a clean, lightweight set of image layers without log files, temporary files, or other artifacts created by the container customization. However, some users may provide container images as they are, without a Dockerfile. As an alternative approach to creating new images, change a running container in place and save its layers to create a new container image. The podman commit command
provides this feature.

Even though the podman commit command is the most straightforward approach to creating new images, it is not recommended because of the image size (commit keeps logs and process ID files in the captured layers), and the lack of change traceability. A Dockerfile provides a robust mechanism to customize and implement changes to a container using a human-readable set of commands, without the set of files that are generated by the operating system.

The syntax for the podman commit command is as follows:

The following table shows the most important options available for the podman commit command:

Option Description
--author "" Identifies who created the container image.
--message "" Includes a commit message to the registry.
--format Selects the format of the image. Valid options
are oci and docker.

The --message option is not available in the default OCI container format.

Eventually, administrators might customize the image and set the container to the desired state. To identify which files were changed, created, or deleted since the container was started, use the diff subcommand. This subcommand only requires the container name or container ID:

The diff subcommand tags any added file with an A, any changed ones with a C, and any deleted file with a D. The diff command only reports added, changed, or deleted files to the container file system. Files that are mounted to a running container are not considered part of the container file system.

To retrieve the list of mounted files and directories for a running container, use the podman inspect command:

Any file in this list, or file under a directory in this list, is not shown in the output of the podman diff command.
To commit the changes to another image, run the following command:


Tagging Images
A project with multiple images based on the same software could be distributed, creating individual projects for each image, but this approach requires more maintenance for managing and deploying the images to the correct locations. Container image registries support tags to distinguish multiple releases of the same project. For example, a customer might use a container image to run with a MySQL or PostgreSQL database, using a tag as a way to differentiate which database is to be used by a container image. Usually, the tags are used by container developers to distinguish between multiple versions of the same software. Multiple tags are provided to identify a release easily.

To tag an image, use the podman tag command:

The IMAGE argument is the image name with an optional tag, which is managed by Podman. The following argument refers to the new alternative name for the image. Podman assumes the latest version, as indicated by the latest tag, if the tag value is absent. For example, to tag an image, use the following command:

The mysql-custom option corresponds to the image name in the container registry. To use a different tag name, use the following command instead:


Removing Tags from Images
A single image can have multiple tags assigned using the podman tag command. To remove them, use the podman rmi command, as mentioned earlier:

Because multiple tags can point to the same image, to remove an image referred to by multiple tags, first remove each tag individually.


Best Practices for Tagging Images
Podman automatically adds the latest tag if you do not specify any tag, because Podman considers the image to be the latest build. However, this may not be true depending on how each project uses tags. For example, many open source projects consider the latest tag to match the most recent release, but not the latest build. Moreover, multiple tags are provided to minimize the need to remember the latest release of a particular version of a project. Thus, if there is a project version release, for example, 2.1.10, another tag called 2.1 can be created pointing to the same image from the 2.1.10 release. This simplifies pulling images from the registry.


Publishing Images to a Registry
To publish an image to a registry, it must reside in the Podman’s local storage and be tagged for identification purposes. To push the image to the registry the syntax of the push subcommand is:

For example, to push the bitnami/nginx image to its repository, use the following command: