Inspecting, saving & pruning images

history, inspect, save/load, prune.

Operating images day to day is a small toolkit used constantly: history and inspect to understand an image, tag to re-name it, save and load to move one without a registry, and the prune family to reclaim the disk that layers quietly eat. inspect dumps the full config — entrypoint, env, user, ports, layers — and is where you confirm what an image does before running it.

$ docker inspect -f 'user={{.Config.User}} entry={{.Config.Entrypoint}} ports={{.Config.ExposedPorts}}' payments-api:1.0
user=nonroot entry=[/server] ports=map[3000/tcp:{}]
$ docker history --no-trunc payments-api:1.0 | head -3   # exactly how each layer was built

Scenario: ship an image to an air-gapped host

A secured environment has no shared registry, so push/pull is not an option. docker save writes an image and all its layers to a tar archive; you carry it across (scp, USB) and docker load reads it back on the far side. save/load is the manual, offline twin of push/pull — and works for multiple images at once.

$ docker save -o payments-1.0.tar registry.internal/payments-api:1.0
$ scp payments-1.0.tar airgap-host:/tmp/
# on the far side, no registry involved:
$ docker load -i /tmp/payments-1.0.tar
Loaded image: registry.internal/payments-api:1.0

Scenario: re-tag one image for a private registry

You built payments-api:1.0 locally and need it in the company registry under a versioned name. tag does not copy anything — it just adds another name pointing at the same image ID — then push uploads it. One image can carry many tags; removing one tag leaves the others (and the layers) intact.

$ docker tag payments-api:1.0 registry.internal/team/payments-api:1.0
$ docker tag payments-api:1.0 registry.internal/team/payments-api:stable
$ docker push registry.internal/team/payments-api:1.0
$ docker push registry.internal/team/payments-api:stable   # same bytes, two names

Scenario: a CI runner out of disk

A build host fails with “no space left on device.” system df shows where it went — images, build cache, stopped containers, dangling volumes. prune reclaims it, but the blast radius matters: plain image prune removes only dangling (untagged) layers, while prune -a removes every image no container currently uses, which on a build box can delete the base images and cache your next build needs.

$ docker system df
TYPE            TOTAL   ACTIVE   RECLAIMABLE
Images          42      6        31.2GB (74%)
Build Cache      210     0        9.8GB
$ docker image prune            # safe: dangling layers only
$ docker builder prune          # clear build cache
$ docker image prune -a         # aggressive: ALL unused images (mind CI caches)