Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 4. Working with container images

The Podman tool is designed to work with container images. You can use this tool to pull the image, inspect, tag, save, load, redistribute, and define the image signature.

4.1. Pulling images from registries
Copy link

Use the podman pull command to get the image to your local system.

Prerequisites

  • The container-tools meta-package is installed.

Procedure

  1. Log in to the registry.redhat.io registry: 

    $ podman login registry.redhat.io
Username: <username>
Password: <password>
Login Succeeded!
    Copy to Clipboard Toggle word wrap

  2. Pull the registry.redhat.io/ubi10/ubi container image: 

    $ podman pull registry.redhat.io/ubi10/ubi
    Copy to Clipboard Toggle word wrap

Verification

  • List all images pulled to your local system: 

    $ podman images
REPOSITORY                           TAG     IMAGE ID      CREATED      SIZE
registry.redhat.io/ubi10/ubi          latest  3269c37eae33  7 weeks ago  208 MB
    Copy to Clipboard Toggle word wrap

You can use secure short names to get the image to your local system. The following procedure describes how to pull a fedora or nginx container image.

Prerequisites

  • The container-tools meta-package is installed.

Procedure

  • Pull the container image:

    • Pull the fedora image: 

      $ podman pull fedora
Resolved "fedora" as an alias (/etc/containers/registries.conf.d/000-shortnames.conf)
Trying to pull registry.fedoraproject.org/fedora:latest…
...
Storing signatures
...
      Copy to Clipboard Toggle word wrap

      Alias is found and the registry.fedoraproject.org/fedora image is securely pulled. The unqualified-search-registries list is not used to resolve fedora image name.

    • Pull the nginx image: 

      $ podman pull nginx
? Please select an image:
registry.access.redhat.com/nginx:latest
registry.redhat.io/nginx:latest
  ▸ docker.io/library/nginx:latest
✔ docker.io/library/nginx:latest
Trying to pull docker.io/library/nginx:latest…
...
Storing signatures
...
      Copy to Clipboard Toggle word wrap

      If no matching alias is found, you are prompted to choose one of the unqualified-search-registries list. If the selected image is pulled successfully, a new short-name alias is recorded locally, otherwise an error occurs.

Verification

  • List all images pulled to your local system: 

    $ podman images
REPOSITORY                                   TAG     IMAGE ID      CREATED        SIZE
registry.fedoraproject.org/fedora            latest  28317703decd  12 days ago    184 MB
docker.io/library/nginx                      latest  08b152afcfae  13 days ago    137 MB
    Copy to Clipboard Toggle word wrap

4.3. Listing images
Copy link

Use the podman images command to list images in your local storage.

Prerequisites

  • The container-tools meta-package is installed.
  • A pulled image is available on the local system.

Procedure

  • List all images in the local storage: 

    $ podman images
REPOSITORY                           TAG     IMAGE ID      CREATED      SIZE
registry.access.redhat.com/ubi10/ubi  latest  3269c37eae33  6 weeks ago  208 MB
    Copy to Clipboard Toggle word wrap

4.4. Inspecting local images
Copy link

After you pull an image to your local system and run it, you can use the podman inspect command to investigate the image. For example, use it to understand what the image does and check what software is inside the image. The podman inspect command displays information about containers and images identified by name or ID.

Prerequisites

  • The container-tools meta-package is installed.
  • A pulled image is available on the local system.

Procedure

  • Inspect the registry.redhat.io/ubi10/ubi image: 

    $ podman inspect registry.redhat.io/ubi10/ubi
…
 "Cmd": [
        "/bin/bash"
    ],
    "Labels": {
        "architecture": "x86_64",
        "build-date": "2020-12-10T01:59:40.343735",
        "com.redhat.build-host": "cpt-1002.osbs.prod.upshift.rdu2.redhat.com",
        "com.redhat.component": "ubi10-container",
        "com.redhat.license_terms": "https://www.redhat.com/...,
    "description": "The Universal Base Image is ...
    }
...
    Copy to Clipboard Toggle word wrap

    The "Cmd" key specifies a default command to run within a container. You can override this command by specifying a command as an argument to the podman run command. This ubi10/ubi container will execute the bash shell if no other argument is given when you start it with podman run. If an "Entrypoint" key was set, its value would be used instead of the "Cmd" value, and the value of "Cmd" is used as an argument to the Entrypoint command.

4.5. Inspecting remote images
Copy link

Use the skopeo inspect command to display information about an image from a remote container registry before you pull the image to your system.

Prerequisites

  • The container-tools meta-package is installed.

Procedure

  • Inspect the registry.redhat.io/ubi10/ubi-init image: 

    # skopeo inspect docker://registry.redhat.io/ubi10/ubi-init
{
    "Name": "registry.redhat.io/ubi10/ubi10-init",
    "Digest": "sha256:c6d1e50ab...",
    "RepoTags": [
        ...
        "latest"
    ],
   "Created": "2020-12-10T07:16:37.250312Z",
    "DockerVersion": "1.13.1",
    "Labels": {
        "architecture": "x86_64",
        "build-date": "2020-12-10T07:16:11.378348",
        "com.redhat.build-host": "cpt-1007.osbs.prod.upshift.rdu2.redhat.com",
        "com.redhat.component": "ubi10-init-container",
        "com.redhat.license_terms": "https://www.redhat.com/en/about/red-hat-end-user-license-agreements#UBI",
        "description": "The Universal Base Image Init is designed to run an init system as PID 1 for running multi-services inside a container
        ...
    }
}
    Copy to Clipboard Toggle word wrap

4.6. Copying container images
Copy link

You can use the skopeo copy command to copy a container image from one registry to another. For example, you can populate an internal repository with images from external registries, or sync image registries in two different locations.

Prerequisites

  • The container-tools meta-package is installed.

Procedure

  • Copy the skopeo container image from docker://quay.io to docker://registry.example.com: 

    $ skopeo copy docker://quay.io/skopeo/stable:latest docker://registry.example.com/skopeo:latest
    Copy to Clipboard Toggle word wrap

4.7. Copying image layers to a local directory
Copy link

You can use the skopeo copy command to copy the layers of a container image to a local directory.

Prerequisites

  • The container-tools meta-package is installed.

Procedure

  1. Create the /var/lib/images/nginx directory: 

    $ mkdir -p /var/lib/images/nginx
    Copy to Clipboard Toggle word wrap

  2. Copy the layers of the docker://docker.io/nginx:latest image to the newly created directory: 

    $ skopeo copy docker://docker.io/nginx:latest dir:/var/lib/images/nginx
    Copy to Clipboard Toggle word wrap

Verification

  • Display the content of the /var/lib/images/nginx directory: 

    $ ls /var/lib/images/nginx
08b11a3d692c1a2e15ae840f2c15c18308dcb079aa5320e15d46b62015c0f6f3
...
4fcb23e29ba19bf305d0d4b35412625fea51e82292ec7312f9be724cb6e31ffd  manifest.json
version
    Copy to Clipboard Toggle word wrap

4.8. Tagging images
Copy link

Use the podman tag command to add an additional name to a local image. This additional name can consist of several parts: <registryhost>/<username>/<name>:<tag>.

Prerequisites

  • The container-tools meta-package is installed.
  • A pulled image is available on the local system.

Procedure

  1. List all images: 

    $ podman images
REPOSITORY                           TAG     IMAGE ID      CREATED      SIZE
registry.redhat.io/ubi10/ubi          latest  3269c37eae33  7 weeks ago  208 MB
    Copy to Clipboard Toggle word wrap

  2. Assign the myubi name to the registry.redhat.io/ubi10/ubi image using one of the following options:

    • The image name: 

      $ podman tag registry.redhat.io/ubi10/ubi myubi
      Copy to Clipboard Toggle word wrap

    • The image ID: 

      $ podman tag 3269c37eae33 myubi
      Copy to Clipboard Toggle word wrap

      Both commands give you the same result.

  3. List all images: 

    $ podman images
REPOSITORY                           TAG     IMAGE ID      CREATED       SIZE
registry.redhat.io/ubi10/ubi          latest  3269c37eae33  2 months ago  208 MB
localhost/myubi                      latest  3269c37eae33  2 months ago  208 MB
    Copy to Clipboard Toggle word wrap

    Notice that the default tag is latest for both images. You can see all the image names are assigned to the single image ID 3269c37eae33.

  4. Add the 10 tag to the registry.redhat.io/ubi10/ubi image using either:

    • The image name: 

      $ podman tag registry.redhat.io/ubi10/ubi myubi:10
      Copy to Clipboard Toggle word wrap

    • The image ID: 

      $ podman tag 3269c37eae33 myubi:10
      Copy to Clipboard Toggle word wrap

      Both commands give you the same result.

Verification

  • List all images: 

    $ podman images
REPOSITORY                           TAG     IMAGE ID      CREATED       SIZE
registry.redhat.io/ubi10/ubi          latest  3269c37eae33  2 months ago  208 MB
localhost/myubi                      latest  3269c37eae33  2 months ago  208 MB
localhost/myubi                      10     3269c37eae33  2 months ago  208 MB
    Copy to Clipboard Toggle word wrap

    Notice that the default tag is latest for both images. You can see all the image names are assigned to the single image ID 3269c37eae33.

After tagging the registry.redhat.io/ubi10/ubi image, you have three options to run the container:

  • by ID (3269c37eae33)
  • by name (localhost/myubi:latest)
  • by name (localhost/myubi:10)

4.9. Building multi-architecture images
Copy link

Prerequisites

  • The container-tools meta-package is installed.

    1. Create Containerfiles for each architecture you want to support.

    2. Build images for each architecture. For example: 

      $ podman build --platform linux/arm64,linux/amd64 --manifest <registry>/<image> .
      Copy to Clipboard Toggle word wrap
      • The --platform linux/arm64,linux/amd64 option specifies the target platforms for which the container image is being built.
      • The --manifest <registry>/<image> option creates a manifest list with the specified name, that is <registry>/<image>, and adds the newly-built images to them. A manifest list is a collection of image manifests, each one targeting a different architecture.

    3. Push the manifest list to the registry: 

      $ podman manifest push <registry>/<image>
      Copy to Clipboard Toggle word wrap

      This manifest list acts as a single entry point for pulling the multi-architecture container.

As a result, you can pull the appropriate container image for your platform, based on a single manifest list.

You can also remove items from the manifest list by using the podman manifest remove <manifest_list> <digest_ID> command, where <digest_ID> is the SHA-256 checksum of the container image. For example: podman manifest remove <registry>/<image> sha256:cb8a924afdf…​.

Verification

  • Display the manifest list: 

    $ podman manifest inspect <registry>/<image>
    Copy to Clipboard Toggle word wrap

4.10. Saving and loading images
Copy link

Use the podman save command to save an image to a container archive. You can restore it later to another container environment or send it to someone else. You can use --format option to specify the archive format. The supported formats are:

  • docker-archive
  • oci-archive
  • oci-dir (directory with oci manifest type)
  • docker-archive (directory with v2s2 manifest type)

The default format is the docker-archive format.

Use the podman load command to load an image from the container image archive into the container storage.

Prerequisites

  • The container-tools meta-package is installed.
  • A pulled image is available on the local system.

Procedure

  1. Save the registry.redhat.io/rhel10/support-tools image as a tarball:

    • In the default docker-archive format: 

      $ podman save -o mysupport-tools.tar registry.redhat.io/rhel10/support-tools:latest
      Copy to Clipboard Toggle word wrap

    • In the oci-archive format, using the --format option: 

      $ podman save -o mysupport-tools-oci.tar --format=oci-archive registry.redhat.io/rhel10/support-tools
      Copy to Clipboard Toggle word wrap

      The mysupport-tools.tar and mysupport-tools-oci.tar archives are stored in your current directory. The next steps are performed with the mysupport-tools.tar tarball.

  2. Check the file type of mysupport-tools.tar: 

    $ file mysupport-tools.tar
mysupport-tools.tar: POSIX tar archive
    Copy to Clipboard Toggle word wrap

  3. To load the registry.redhat.io/rhel10/support-tools:latest image from the mysupport-tools.tar: 

    $ podman load -i mysupport-tools.tar
...
Loaded image(s): registry.redhat.io/rhel10/support-tools:latest
    Copy to Clipboard Toggle word wrap

4.11. Redistributing UBI images
Copy link

Use podman push command to push a UBI image to your own, or a third party, registry and share it with others. You can upgrade or add to that image from UBI dnf repositories as you like.

Prerequisites

  • The container-tools meta-package is installed.
  • A pulled image is available on the local system.

Procedure

  1. Optional: Add an additional name to the ubi image: 

    # podman tag registry.redhat.io/ubi10/ubi registry.example.com:5000/ubi10/ubi
    Copy to Clipboard Toggle word wrap

  2. Push the registry.example.com:5000/ubi10/ubi image from your local storage to a registry: 

    # podman push registry.example.com:5000/ubi10/ubi
    Copy to Clipboard Toggle word wrap
Important

While there are few restrictions on how you use these images, there are some restrictions about how you can refer to them. For example, you cannot call those images Red Hat certified or Red Hat supported unless you certify it through the Red Hat Partner Connect Program, either with Red Hat Container Certification or Red Hat OpenShift Operator Certification.

4.12. Removing images
Copy link

Use the podman rmi command to remove locally stored container images. You can remove an image by its ID or name.

Prerequisites

  • The container-tools meta-package is installed.

Procedure

  1. List all images on your local system: 

    $ podman images
REPOSITORY                           TAG     IMAGE ID      CREATED      SIZE
registry.redhat.io/rhel10/support-tools     latest  4b32d14201de  7 weeks ago  228 MB
registry.redhat.io/ubi10/ubi          latest  3269c37eae33  7 weeks ago  208 MB
localhost/myubi                      X.Y     3269c37eae33  7 weeks ago  208 MB
    Copy to Clipboard Toggle word wrap

  2. List all containers: 

    $ podman ps -a
CONTAINER ID  IMAGE                                    COMMAND          CREATED        STATUS            PORTS   NAMES
7ccd6001166e  registry.redhat.io/rhel10/support-tools:latest  usr/bin/bash  6 seconds ago  Up 5 seconds ago          my-support-tools
    Copy to Clipboard Toggle word wrap

    To remove the registry.redhat.io/rhel10/support-tools image, you have to stop all containers running from this image by using the podman stop command. You can stop a container by its ID or name.

  3. Stop the my-support-tools container: 

    $ podman stop my-support-tools
7ccd6001166e9720c47fbeb077e0afd0bb635e74a1b0ede3fd34d09eaf5a52e9
    Copy to Clipboard Toggle word wrap

  4. Remove the registry.redhat.io/rhel10/support-tools image: 

    $ podman rmi registry.redhat.io/rhel10/support-tools
    Copy to Clipboard Toggle word wrap

    • To remove multiple images: 

      $ podman rmi registry.redhat.io/rhel10/support-tools registry.redhat.io/ubi10/ubi
      Copy to Clipboard Toggle word wrap

    • To remove all images from your system: 

      $ podman rmi -a
      Copy to Clipboard Toggle word wrap

    • To remove images that have multiple names (tags) associated with them, add the -f option to remove them: 

      $ podman rmi -f 1de7d7b3f531
1de7d7b3f531...
      Copy to Clipboard Toggle word wrap

Verification

  • List all images by using the podman images command to verify that container images were removed.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat