Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 37 ยท Containers and Images

Image Storage, Layers, Tags, Save and Load

Look inside Podman images: layers and history, tagging, removing and pruning, save and load as tar files, export and import, copying between machines and disk usage.

Images are the part of container work that quietly eats your disk. Understanding what an image is made of, how names point to it, and how to move or delete it will keep your machine tidy and let you work offline, in air-gapped networks, or between users on the same host.

An image is a stack of layers plus a configuration (command, environment, exposed ports, labels) and a manifest that lists them by digest. Layers are read-only and shared between images. When you run a container, Podman adds one thin writable layer on top.

Looking inside an image

Terminal
podman images
podman images --digests
podman image inspect docker.io/library/alpine:3.20
podman history docker.io/library/alpine:3.20
podman image tree docker.io/library/alpine:3.20
  • podman images shows the repository, tag, short image ID, age and size. The same image ID may appear under several names.
  • podman image inspect returns the configuration and the list of layer digests.
  • podman history lists the steps that made the image, with the size each added. A Containerfile with many RUN lines shows up as many layers.
  • podman image tree prints the layer tree (when the command is available in your version).

A layer is identified by the SHA-256 of its content. That is why layers can be shared: two images using the same base have the same digest for that part, so Podman keeps it once on disk.

Names are labels, not copies

Tagging adds another name to an image. It does not duplicate any data.

Terminal
podman tag docker.io/library/alpine:3.20 localhost/my-alpine:v1
podman tag localhost/my-alpine:v1 registry.example.com/team/alpine:v1
podman images

Now one image ID has three names. podman rmi localhost/my-alpine:v1 removes just that name; the layers are deleted only when the last name and every container using the image are gone. Images built locally without a registry get the localhost/ prefix automatically.

Here is a stand-in that models names pointing to image IDs and removal by reference counting. It is JavaScript, not Podman.

JS Stand-in: tags and reference counting

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Removing and pruning

Terminal
podman rmi docker.io/library/alpine:3.20
podman rmi --force IMAGE_ID          # also removes containers that use it
podman image prune                    # remove dangling images (no name)
podman image prune --all              # remove every image not used by a container
podman image prune --filter until=720h

A dangling image is one that lost its tag, typically after you rebuilt an image with the same name: the old build keeps its layers but has no name. They are safe to prune. --all is more aggressive and deletes images you may want again; Podman asks for confirmation.

Disk usage

Terminal
podman system df
podman system df --verbose

The report has rows for images, containers and local volumes, with total and reclaimable sizes. If your home directory fills up, rootless storage under ~/.local/share/containers/storage is the first place to look. Move it with graphroot in ~/.config/containers/storage.conf (after podman system reset, which deletes everything) if you want it on another disk.

Moving images as files

When there is no registry, or you are offline, use tar archives.

Terminal
podman save --output alpine.tar docker.io/library/alpine:3.20
podman save --format oci-archive -o alpine-oci.tar docker.io/library/alpine:3.20
podman load --input alpine.tar
  • save writes an image with its layers, names and history into a tar archive. Several images can go in one file.
  • load reads such an archive back and recreates the names.
  • Compress with gzip alpine.tar or podman save ... | gzip > alpine.tar.gz; load reads compressed archives too.

A different pair works on containers:

Terminal
podman export --output web-rootfs.tar web
cat web-rootfs.tar | podman import - localhost/web-flat:1

export writes only the container's file system as one flat tar (no history, no layers, no metadata). import turns such a tar into a new single-layer image. You rarely need this; it can be useful to flatten an image or to start from a custom root file system.

To copy straight to another machine over SSH, Podman has a helper:

Terminal
podman image scp alice@build-host::localhost/app:1.0

Skopeo can also copy between storage kinds without pulling into local storage first:

Terminal
skopeo copy docker://docker.io/library/alpine:3.20 oci-archive:alpine-oci.tar

Storage drivers and the overlay layout

On modern kernels, Podman uses the overlay driver. Under ~/.local/share/containers/storage/overlay each layer is a directory containing a diff folder with that layer's files, and a container mounts them together with the kernel's overlayfs: lower layers read-only, one writable "upper" directory. The first write to a file that lives in a lower layer copies it up to the upper layer (copy on write), which is why writing large files inside a container is slower than writing to a volume, and why the writable layer should not hold your data.

In rootless mode Podman uses the kernel's native rootless overlay when available (Linux 5.13 and later) and otherwise fuse-overlayfs. podman info shows graphDriverName and, for rootless, the graphOptions. The older vfs driver is always available as a fallback, but it copies the full file system for every layer, so it is slow and uses a lot of disk.

The following stand-in models copy-on-write to show the idea in a few lines.

JS Stand-in: copy-on-write layers

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The last line is the important one: deleting a file in a later layer does not shrink the image, because the old layer still contains it. That is why build tips like "remove temporary files in the same RUN step" exist.

Keeping things tidy

  • Use podman system df regularly and prune dangling images.
  • Pin base images by version, and rebuild on a schedule to get security updates.
  • Delete images you no longer use with podman rmi, and remove stopped containers first.
  • Keep large data in volumes (Volumes and Bind Mounts), not in the writable layer.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does podman tag SOURCE NEWNAME do?

    A tag is only a reference. The layers are stored once, whatever number of names point to them.
  2. 2. What is a dangling image?

    When a new build takes the name, the old image loses it and shows as <none>. podman image prune removes them.
  3. 3. Which pair moves an image with all its layers and tags as a tar file?

    save and load work on images; export and import work on a container's flat file system.
  4. 4. Why does deleting a file in a later RUN step not make the image smaller?

    Layers are additive. A deletion becomes a whiteout in a new layer, but the old data is still in the earlier layer.

Summary

  • An image is a manifest, a configuration and a stack of shared read-only layers; containers add a writable layer.
  • Tags are cheap names for the same image ID; podman rmi removes names and frees layers when nothing else uses them.
  • podman history, image inspect and system df show contents and disk use; prune dangling images regularly.
  • save and load move images as tar files; export and import flatten a container's file system.
  • Overlay storage copies files up on first write; keep real data in volumes.

Next: Health Checks and Restart Policies