Inspecting, exporting and cleaning up images

image ls on Docker 29, save and load, disk usage and pruning.

Someone who learned Docker a few years ago types docker image ls on a Docker 29 host and gets a table they don't recognise. You'll work in ~/lab/imgmgmt on the main VM, where the lesson files (a Dockerfile) go. First pull the two images you'll inspect; on a VM that already has them, the pull only confirms the tags. Then list them. There's no REPOSITORY, TAG or SIZE column any more:

Docker 29 made this "new view" the default. Each row is one image name. ID is the first 12 hex digits of the image's digest. On a host that uses the containerd image store (every fresh 29 install), that's the digest of the image index. It's the same value a registry reports for the tag ("Image anatomy: index, manifest, config and layers" shows where it comes from). The two size columns answer different questions. CONTENT SIZE is what the image's compressed blobs take up, roughly what a pull downloads. DISK USAGE adds the unpacked filesystem snapshot that containers start from. The containerd store keeps both copies, which is why alpine's 4.28MB of content costs 13.6MB of disk. The legacy graph-driver store kept only the unpacked layers, so you can't compare the old SIZE column with this one.

Platforms, the classic table and the U flag

Most official images are multi-platform: one name, one index, a manifest per CPU architecture. --tree expands a row into the platforms the index lists:

Only linux/arm64/v8 holds data, because the lab VM is arm64 and docker pull fetched just that platform. The other rows are entries in the index whose content never came down, and they cost nothing. On an amd64 machine the linux/amd64 row carries the data and the arm64 row shows 0B. The CLI help still marks --tree as experimental. On 29.8.2, the last version whose help was checked, docker image ls had no --platform flag; docker image inspect, docker image history, docker save, docker load and docker run take one.

Scripts that parse the old columns don't break silently, because any explicit layout switches back to the classic table. --digests is one of them, and so is --format:

With the containerd store the DIGEST column and the IMAGE ID are the same value. The last column you'll want to know is EXTRA. Start a container and the image gets a U, for in use:

"In use" means a container exists from that image, running or stopped. That's the line docker image prune -a draws later on.

History: find the step that made it big

When an image grows between two releases, one instruction usually explains it. Build the lab image and read its history. Its Dockerfile writes 3 MB of random bytes in one RUN and a small text file in another:

FROM alpine:3.24
# 3 MB of random bytes: a layer big enough to spot in docker image history
RUN head -c 3000000 /dev/urandom > /opt/blob.bin
ARG BUILD=1
RUN echo "lab-tool build $BUILD" > /build.txt
CMD ["cat", "/build.txt"]

The newest step is at the top. The 3.01MB row is the RUN head -c 3000000 ... line, so that's where you look. The two bottom rows are alpine's own build, which is why they're four days old in this run. <missing> in the IMAGE column is normal. BuildKit records history entries, not an image per step, and only the final image has an ID. Rows with 0B (CMD, ARG) changed only the image config. Commands are cut at 45 characters. Add --no-trunc to read them whole; that's also how you find a secret someone passed in a build argument. History shows the instruction, not the files. When you need to know which files a layer holds, extract it (as in "Image anatomy: index, manifest, config and layers") or use a tool such as dive.

Rebuilding under the same tag

Change the build argument and build again under the same name. On the legacy store this left the previous image behind as a nameless <none> image. A CI host that rebuilt fifty times a day collected hundreds of them. On Docker 29 with the containerd store, look for one:

There's one lab-tool:1, and the dangling=true filter finds nothing. The containerd store drops the old image record when the tag moves to the new build, unless something still points at it. The last section repeats the experiment on the legacy store, where the old image does stay behind. The bytes of earlier builds didn't vanish, though. They live on in the build cache, which docker system df reports next to images, containers and volumes:

Read RECLAIMABLE, not SIZE. Images count as reclaimable when no container uses them; the active one here is the nginx image behind lab-web. The Build Cache row is the one that grows on a build host. It holds every RUN result and copied context BuildKit keeps for later builds. The numbers belong to everything built on this VM, so yours will differ. docker system df -v breaks each row down per image, container, volume and cache record. It also shows how much of each image is shared with others.

Moving an image without a registry

An air-gapped host can't pull. docker save writes images to a tar archive and docker load reads one back. Record the ID first, so you can prove the round trip kept the image intact:

On the containerd store the archive is an OCI image layout. It has oci-layout, an index.json naming the image, and content-addressed files under blobs/sha256/. There's also a Docker-style manifest.json, so older docker load versions can read it. The ID after the load is the one before it, because the blobs and their digests didn't change. docker load also accepts a gzip-compressed archive, so docker save lab-tool:1 | gzip > lab-tool-1.tar.gz is fine for the transfer. Two practical cautions apply. The archive holds every layer, including anything a careless build left in an early one. So treat it with the same care as the image in a private registry. And it's no replacement for docker export, which flattens a container's filesystem into a tar and loses the config, history and layers.

save can only write what the store has. A pulled multi-platform image has content for one platform, as the tree view showed, and asking for another fails:

To carry a platform you don't run locally, pull it first with docker pull --platform linux/s390x ... on a connected machine. Then save with the same --platform. Without the flag, save writes the platforms that are present.

Pruning with filters

docker image prune with no flags removes dangling images only, which on a containerd-store host is usually nothing. -a widens it to every image no container uses, tagged or not, base images included. On a build host that wipes the bases your next build needs. On a production host it can take the previous release you'd roll back to. So narrow -a with filters. Build three more labelled images, one of them marked keep=true. Then preview the selection with docker image ls, which accepts the same label filters:

Filters on different keys are ANDed: label=secopslog.lab=true selects the lab images and label!=keep=true then excludes the marked one. Each removed image lists three digests: the index and the two manifests it pointed to (the image manifest and its attestation manifest). Note the total: 40.19kB for three images of 19.5MB each. The 3 MB layer and the alpine base are shared with lab-keep:1 and every other alpine image. A prune frees only data nothing else references. So measure with docker system df before and after, rather than trusting the arithmetic of the image list.

The other filter you'll meet is until. The documentation describes it as "images created before" a time. What counts as created depends on the image store, as the last section shows.

On the disposable VM: age, cache budgets and the legacy store

The rest runs on secopslog-docker-sec. Your login there isn't in the docker group, so every command uses sudo. Fetch the lesson files into ~/lab/imgmgmt on that VM as well and work there. Start with the age filter. Pull alpine, check the creation date the image carries, and prune everything "older than a day":

The image says it was created on 21 October, days before this run, yet nothing was removed. On the containerd store the filter left alone an image that arrived seconds earlier. In this lab it behaved as if it counted from when the image record was created on this host, not from the build date in the config. Keep that in mind before you rely on until, because the legacy store, a few steps further down, does the opposite.

Next, the build cache. Build three variants, remove the image, and look at what the cache holds:

While lab-tool:1 existed, almost none of the 19.57MB of build cache was reclaimable. On the containerd store the cache records and the image share the same snapshots, so the Build Cache SIZE overlaps with the Images row. With the image gone, 6.065MB became private to the cache. docker buildx du lists each record, and a * marks one shared with an image. Now give the cache a budget:

--reserved-space deletes cache records, least recently used first, until the cache fits the budget or nothing reclaimable is left. Here it removed six records (6.065MB) and stopped at 13.5MB, above the 5MB budget. What remains is one record, the alpine snapshot that alpine:3.24 still uses, so none of it is reclaimable. Buildx 0.38 also offers --max-used-space and --min-free-space. Older guides use --keep-storage, which the help stopped listing by Buildx 0.37. --filter until=24h removes records not used in the last day. An unfiltered docker builder prune -f removes all reclaimable cache, and the next build starts cold.

Finally, the legacy image store. Hosts upgraded from Docker 28 or older keep it until someone migrates them, so you'll meet it. Switch this VM to it with the procedure from "Configuring the daemon safely". Back up the current daemon.json (or record {} when there's none, as here). Merge the one key into the backup with jq, so anything already in the file survives. Validate, and only then restart. "Where Docker keeps data" covers the stores themselves:

The driver is now overlay2 and the image list is empty. Switching stores hides the other store's images without deleting them. Repeat the age experiment here:

On the legacy store until compares the creation date from the image config. So an image pulled a second ago but built on 21 October is gone. A nightly "prune everything older than a day" job on such a host removes freshly pulled bases and keeps recent local builds. Know which store a host runs before you schedule until. Add a label filter too, so the job only touches images you own. Now rebuild under one tag, as in the main lab:

Here the second build leaves the first behind. The new view lists it as <untagged> (the classic table calls it <none>), and dangling=true finds it. Plain docker image prune removes it, and it freed nothing because every layer was shared with the new build. The ID also means something else on this store. It's the digest of the image config, which the Config entry of a saved archive confirms. On the containerd store it's the index digest. Keep that in mind when a script compares IDs across hosts.

Switching back has a trap. Restore the backup and restart, and the daemon stays on overlay2, because it now finds legacy-store data and keeps using it. Only an explicit true brings the containerd store back, with the alpine image pulled at the start of this section still in it. There's one more thing you need to know first. systemd allows only three docker.service starts per minute, and this section has used them up. The next restart would fail with start request repeated too quickly. systemctl reset-failed docker clears the counter (waiting a minute works too):

Leave that features line in daemon.json for as long as the legacy directories exist on the VM. Without it the daemon falls back to them on the next start. "Configuring the daemon safely" shows how the leftover directories are removed, and recreating the sec VM clears everything.

Try this

Before the main VM cleanup, rerun the docker image ls preview with only label=secopslog.lab=true, dropping the label!=keep=true exclusion. Predict which extra name you'll see, then compare with the preview above. That's the image the keep label saved from the prune.

Remember

Before any scheduled prune, run docker system df and narrow -a with a label filter, because the image list's sizes lie about what a prune frees: three 19.5MB images gave back 40.19kB. Check which image store the host runs before you trust until. The same "older than a day" filter removed nothing on the containerd store and deleted a freshly pulled alpine on the legacy one.

Related