Image lifecycle — pull, tag, push, prune, retain · Docker & Containers

An image is built, tagged, pushed, pulled, run, and eventually deleted. Five of those six steps are routine. The sixth is where estates lose the ability to roll back, and it is almost always run by somebody trying to be helpful about disk space.

Build and tag

Configuration changebuild— Two tags on one build: one immutable, one convenient.

SHA=$(git rev-parse --short HEAD)
REPO=registry.example.com/myorg/myapp

docker buildx build \
--tag "$REPO:$SHA" \
--tag "$REPO:1.0.0" \
--load \
.

docker tag adds a name to an image that already exists. It copies nothing and creates no layer, so many tags on one image cost the disk of one image.

Push

Service impact possiblepush— Only missing blobs transfer. Everything already in the registry is skipped.

$ docker push registry.example.com/myorg/myapp:1.0.0

The push refers to repository [registry.example.com/myorg/myapp]
9c1b6dd6c1e6: Pushed
4a2f0c8b7e31: Layer already exists
b8d2e0f4a917: Layer already exists
1.0.0: digest: sha256:0c1a2f9b7d3c4e5a6f7089abcdef0123d5f28ef21aabd54d6a48d8b9d3b8e5b1 size: 1789

Illustrative output

Layer already exists is deduplication doing its job: the registry stores blobs by digest, so ten images sharing a base upload it once. The digest: line is the value to record — it is the index digest, and it is what a pin should reference.

Pushing an image that is entirely unchanged transfers a manifest and nothing else. A suspiciously fast push is normal, not a sign something went wrong.

Pull

Read-only / Safepull— The Digest and Status lines are the two that matter.

$ docker pull registry.example.com/myorg/myapp:1.0.0

1.0.0: Pulling from myorg/myapp
Digest: sha256:0c1a2f9b7d3c4e5a6f7089abcdef0123d5f28ef21aabd54d6a48d8b9d3b8e5b1
Status: Image is up to date for registry.example.com/myorg/myapp:1.0.0

Illustrative output

Status: Image is up to date means the tag still resolves to the digest you already have. Status: Downloaded newer image means it did not — which, on a tag you believed was stable, is drift you have just discovered by accident. Capture that line in deploy logs; it is a free drift detector.

docker run pulls implicitly when the image is absent. The --pull flag takes always, missing (the default) or never:

Configuration changepull policy— never turns a silent implicit pull into an explicit failure.

# Fails immediately if the image is not already on the host.
docker run --pull=never --rm registry.example.com/myorg/myapp:1.0.0 --version

--pull=never is worth considering for production, not because pulling is bad but because it moves the registry dependency out of the moment of failure. With missing, a container that gets recreated during an incident quietly acquires a dependency on the registry being reachable, at exactly the point you least want one. With never, the image is either staged or the command fails at once and tells you so.

Prune — the step that loses your rollback

The maintenance window that deleted the way back

The sequence has run on every estate that has one.

A maintenance window starts. Services are stopped so the host can be patched.
/var/lib/docker is at 85%, and somebody runs docker image prune -a while the containers happen to be down.
docker image prune -a removes all images not referenced by a container. A stopped container still counts as a reference. A service brought down with docker compose down, which removes its containers, does not.
The window ends. Services are started. Every image pulls from scratch.
One of them does not come back: the registry retired the tag, or the tag moved and the new content is broken, or the registry is simply unreachable from this host at 04:00 because the change also touched the network.

Now you want the previous image. It was on this host forty minutes ago and it is not any more.

The subtlety worth naming is step 3. docker compose stop leaves the containers in place, so their images are protected. docker compose down removes them, so the images become prunable — and the two commands look interchangeable in a runbook written by somebody who has never pruned.

What each prune command considers 'unused'

Precision here is worth more than any amount of general caution, because the commands differ in exactly the way that matters.

docker image prune removes dangling images only. Dangling means untagged and a leaf of the image tree — the docs describe how they arise: “These images occur when a new build of an image takes the repo:tag away from the image ID, leaving it as untagged.” This is nearly always safe. It is what you want on a build host.

docker image prune -a removes all images not referenced by any container — running or stopped. This is not “unused images”. An image nothing currently runs but which you need tomorrow is, by this definition, unused.

docker system prune removes all stopped containers, all networks not used by a container, all dangling images, and unused build cache. Note the first item: it deletes containers, which then stops protecting their images.

docker system prune -a adds “all unused images not just dangling ones”, so it is the previous command plus the aggressive image prune — with the container removal happening first, which widens what counts as unreferenced.

docker system prune --volumes additionally removes anonymous volumes not used by a container. The documentation explains the default: “volumes aren’t removed to prevent important data from being deleted if there is currently no container using the volume.” That flag turns a cleanup into a data-loss operation, and a database container recreated without its named volume is not what people expect anonymous to mean.

Filters combine in a documented way that is easy to get backwards: filters with different keys are ANDed (an image must satisfy all of them to be pruned), and filters with the same key are ORed.

Destructiveprune— Removes images. Read the filter semantics above before running the -a form.

# Safe: dangling only.
docker image prune

# Aggressive: everything no container references, older than 30 days.
docker image prune -a --filter "until=720h"

# Protect a set with a label applied at build time.
docker image prune -a --filter "label!=retain=true"

Read-only / Safedry run— List what an aggressive prune would remove, before removing anything.

# Every image ID currently referenced by a container, running or not.
IN_USE=$(docker ps -aq | xargs -r docker inspect --format '{{.Image}}' | sort -u)

echo "Would be removed:"
docker image ls --format '{{.ID}} {{.Repository}}:{{.Tag}}' | while read -r id ref; do
  full=$(docker image inspect --format '{{.Id}}' "$id")
  echo "$IN_USE" | grep -q "$full" || echo "  $ref ($id)"
done

Run that, read it, and only then decide. On a production host the output should be short enough to read; if it is not, that is itself the finding.

A retention policy that keeps the rollback

Label every image at build time with something you can filter on: --label retain=true for release builds, nothing for CI scratch builds.
Prune dangling images aggressively and on a schedule. That is the bulk of the waste on a build host and it is safe.
Prune -a only with a until= window long enough to cover your rollback horizon. If you might roll back a month, do not prune anything younger than a month.
Before any planned prune, record the digests currently deployed: docker ps -q | xargs -r docker inspect --format "{{.Image}}". That list is your recovery plan.
Keep the current and the previous release digest referenced somewhere the prune cannot reach — a tag in the registry, and ideally a docker save tarball on separate storage for the current release.
Never run docker system prune -a from a scheduled job on a production host. The container-removal step makes its blast radius depend on what happened to be running when it fired.
Monitor /var/lib/docker free space so pruning is a planned action and never an emergency one. Every bad prune in this lesson was run by somebody under disk pressure.

Registry-side retention is a different mechanism

Deleting a tag in a registry does not free space. The blobs remain until garbage collection runs, and for the reference distribution registry that is a manual command, not a scheduled policy:

Destructiveregistry GC— Manual, offline-ish, and irreversible. Read the project documentation before running it on a registry anyone depends on.

# Requires storage.delete.enabled in config.yml, and the registry
# should be stopped or in read-only mode while this runs.
registry garbage-collect --dry-run /etc/distribution/config.yml

# --delete-untagged also removes manifests that no tag points at.
registry garbage-collect --delete-untagged /etc/distribution/config.yml

Two consequences follow.

A digest pin can outlive its content. --delete-untagged removes exactly the manifests that a digest-only reference depends on. If you pin a digest, keep a tag on it too, or the registry’s own housekeeping will eventually break your deployment.

Disk on the registry does not shrink when you delete tags. Teams regularly delete hundreds of tags, see no change in storage, and conclude the deletion failed. It did not; GC has not run.

Hosted registries — Docker Hub, ECR, GCR, Harbor, Artifactory — each implement their own retention rules, with their own definitions of what is eligible. Read yours before you rely on a digest surviving. Do not assume the semantics of one transfer to another.

Moving images without a registry

Configuration changesave and load— Air-gapped transfer, and a rollback artefact that no prune can delete.

IMAGE=registry.example.com/myorg/myapp:1.0.0

# On the connected host.
docker save "$IMAGE" | gzip > myapp-1.0.0.tar.gz
sha256sum myapp-1.0.0.tar.gz > myapp-1.0.0.tar.gz.sha256

# On the target host, after transferring both files.
sha256sum -c myapp-1.0.0.tar.gz.sha256
gunzip -c myapp-1.0.0.tar.gz | docker load

docker image inspect --format '{{.Id}}' "$IMAGE"

docker save preserves the tags and produces a self-contained archive. It is the cheapest insurance against the prune scenario above: a tarball on separate storage is a rollback target that no host-side command can remove.

docker export is a different thing and is regularly confused with it — it writes a container’s flattened filesystem with no layers, no history, and no image configuration, so an export followed by import loses the entrypoint, the environment, and the user. Use save/load for images and export/import only when you specifically want a flattened snapshot.

Verification that can fail

Read-only / Saferollback readiness— Assert that the image each running container needs is still present, and that a previous release exists.

FAIL=0

for id in $(docker ps -q); do
  name=$(docker inspect --format '{{.Name}}' "$id")
  img=$(docker inspect --format '{{.Image}}' "$id")
  if ! docker image inspect "$img" >/dev/null 2>&1; then
      echo "FAIL $name runs an image that is no longer in the local store" >&2
      FAIL=1
  fi
done

if [ "$(docker image ls --filter 'label=retain=true' -q | wc -l)" -lt 2 ]; then
  echo "FAIL fewer than two retained releases on this host: no rollback target" >&2
  FAIL=1
fi

[ "$FAIL" -eq 0 ] && echo "rollback target present"
exit "$FAIL"

What happens if you prune while a container is running from a deleted tag?

The container keeps running, and this is the case that produces the most confident wrong conclusions.

A running container holds a reference to its image, so the image cannot be removed while it runs — docker rmi reports “image is being used by running container” and refuses. What can be removed is the tag. Untag the image and the container continues perfectly: it was bound to a digest at create time, not to a name.

The result is a container whose image now shows as <none>:<none> in docker image ls. Everything works. Then:

The container is stopped and removed for a routine change, and the image becomes prunable. The next prune takes it.
Somebody tries to recreate the container from the Compose file and the pull fails, because the tag it names no longer resolves to that content.
The image ID is not enough to reconstruct the reference — you can run it, but you cannot tell anyone else which release it was without the tag.

The check that catches this before it matters is one line, and it belongs in your host health check rather than in an incident:

Read-only / Safeuntagged in production— Find running containers whose image has lost its name.

docker ps -q | while read -r id; do
  name=$(docker inspect --format '{{.Name}}' "$id")
  tags=$(docker inspect --format '{{.Image}}' "$id" \
         | xargs -r docker image inspect --format '{{len .RepoTags}}')
  [ "$tags" = "0" ] && echo "UNTAGGED: $name is running an image with no tags" >&2
done
echo "check complete"

Why this matters

The image lifecycle is well-behaved right up to the point where somebody needs disk space, and then it becomes the mechanism by which an estate loses its ability to go back.

Everything in this lesson reduces to one question you should be able to answer about any production host at any moment: if this deploy is bad, what exactly do I run instead, and is it still here? A retention policy is just that question written down. A docker save tarball on separate storage is the same question with a physical answer.

The commands themselves are simple. What is not simple, and what genuinely catches experienced people, is the precise definition of “unused” — that a stopped container protects its image but a removed one does not, that compose stop and compose down therefore differ in a way that matters, and that the registry’s own garbage collection can delete a digest you pinned. None of those are obvious, and all of them are discovered the same way if you do not learn them in advance.