Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 37 ยท Systemd and Operations

Storage Maintenance and Cleanup

Keep Podman tidy: see disk usage with podman system df, prune containers, images, volumes and networks safely, understand storage locations, migrate after upgrades and reset.

Containers are cheap to create, which means they pile up. Old images, stopped containers, unused volumes and build caches slowly eat your disk. Regular, safe cleanup is part of operating Podman, and so is knowing where its data lives and what to do after upgrades.

This lesson explains disk usage, every prune command and what it will and will not delete, storage locations for root and rootless Podman, and maintenance commands. Cleanup commands change real data, so they are read-only here; the stand-ins simulate prune logic and format sizes.

What takes space

Terminal
podman system df
podman system df -v

The summary lists Images, Containers and Local Volumes with the total size and how much is reclaimable. -v breaks it down per image, container and volume. The numbers to watch:

  • Images: each image's unique layers; shared layers are counted once.
  • Containers: the writable layer of each container (files it created or changed).
  • Volumes: your actual data. Reclaimable here means "not used by any container", which may still be data you want.

Pruning, one resource at a time

Command Removes
podman container prune All stopped containers
podman image prune Dangling images (untagged, no longer referenced)
podman image prune -a Every image not used by a container
podman volume prune Volumes not used by any container
podman network prune Networks not used by any container
podman pod prune Stopped pods
podman system prune Stopped containers, pods, unused networks and dangling images (and with -a all unused images)
podman system prune --volumes The above plus unused volumes

Useful flags: --filter until=24h (older than a day), --filter label=app=test, -f to skip the confirmation prompt (needed in scripts).

podman volume prune and system prune --volumes delete data permanently. A volume that is "unused" only because its container is stopped will be removed. List first with podman volume ls and check what each volume holds, or label important volumes and use --filter label!=keep.

Dangling versus unused

A dangling image has no tag. It is usually the previous version of an image after you rebuilt a tag. An unused image has a tag but no container uses it. image prune removes only the first kind; image prune -a removes both. This stand-in applies those rules to a sample inventory:

Python What would prune remove? (stand-in)

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Removing precisely

Terminal
podman rm -f NAME                       # remove a container (even running)
podman rm --all --force                 # every container
podman rmi IMAGE                        # remove one image (fails if a container uses it)
podman rmi --all --force                # every image
podman volume rm NAME
podman pod rm --force NAME

To avoid accumulating containers in the first place, run throwaway ones with --rm, and give long-lived data a named volume.

Where Podman stores things

What Rootless Rootful
Images, containers, layers ~/.local/share/containers/storage /var/lib/containers/storage
Config ~/.config/containers/ /etc/containers/
Runtime state (sockets, locks) $XDG_RUNTIME_DIR/containers /run/containers

Check the real paths with:

Terminal
podman info --format '{{.Store.GraphRoot}}'
podman info --format '{{.Store.RunRoot}}'

Do not delete files in the storage directory by hand: use Podman commands, because layers are shared and reference-counted. If the disk is nearly full, move the graph root by editing ~/.config/containers/storage.conf (graphroot = "/bigdisk/containers") before creating anything, or reset after changing it.

Python Human-readable sizes (stand-in)

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

(Podman's tables use decimal units, kB and MB, like the stand-in.)

After upgrades, and when things go wrong

Terminal
podman system migrate        # refresh containers after an upgrade or config change (restarts them)
podman system renumber       # fix lock numbering after changing the lock count
podman system check          # check storage consistency (--repair to fix)
podman system reset          # DELETE ALL images, containers, volumes, networks
podman info                  # versions, storage, network backend, cgroup mode

podman system migrate is the usual answer to errors that appear after a major upgrade or a change of containers.conf (for example the cgroup manager or runtime), because existing containers keep the old settings until recreated. podman system reset is the nuclear option: after confirmation it removes everything for the current user, which sometimes fixes a corrupted rootless storage.

A cleanup routine

  • Run workloads with --rm where state is not needed.
  • Label important volumes; prune with filters.
  • Schedule podman system prune -f --filter until=168h weekly via a systemd timer (be sure it does not use --volumes).
  • Keep images lean (see Multi-Stage Builds and Build Caching) so each pull and prune moves less data.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command shows disk usage and what is reclaimable?

    podman system df summarizes images, containers and volumes and the reclaimable amounts.
  2. 2. What does podman image prune (without -a) remove?

    Without -a it removes only dangling images; -a also removes tagged images not used by any container.
  3. 3. Why is podman volume prune risky?

    A volume belonging to a stopped container counts as unused and is deleted permanently.
  4. 4. Where is rootless image and container storage by default?

    Rootless graph root is under ~/.local/share/containers/storage; /var/lib/containers is for rootful.

Summary

  • podman system df shows usage; system prune, image prune, container prune, volume prune and network prune reclaim it.
  • Dangling images are untagged; unused images are tagged but not in use; -a removes both.
  • Volume pruning deletes data permanently: check and label first.
  • Rootless and rootful Podman store data in different places; change them in storage.conf.
  • podman system migrate helps after upgrades; podman system reset removes everything.

Next: Project: A Web App and Database in a Pod