Clean up unused Docker images

docker image prune removes dangling images. Adding -a also removes tagged images that no container references. Either operation can discard an image you intended to keep for debugging or rollback, so choose a retention policy before reclaiming space.

Understand the candidate sets

docker image ls --filter dangling=true
docker image ls --digests
docker system df -v

A dangling image is an untagged image eligible for dangling-image cleanup, often left after rebuilding or retagging. A <none> entry is not a complete explanation of all layer relationships or reclaimable bytes.

An unused image has no container reference. For docker image prune -a, references from stopped containers count too. A named image saved for a future rollback can be unused even when it is operationally important.

Choose the cleanup command

docker image prune
# Broader alternative:
docker image prune -a

These prompt before proceeding. -f skips confirmation. Shared layers needed by retained images are not simply deleted, so summed image sizes are not a reliable estimate of reclaimed disk space.

docker system prune -a is broader again: it removes stopped containers, unused networks, and build cache as well as eligible images. A stopped container that would protect its image during image-only pruning may be removed during system pruning, leaving the image eligible.

Apply an age or ownership policy

docker image prune -a \
  --filter until=720h \
  --filter label=cleanup=approved

This targets qualifying unused images created more than 720 hours ago and carrying the specified image label. It is creation age, not time since last use or pull. Merely sorting CreatedAt text and taking the first few rows does not implement “older than a week.”

Filters do not automatically preserve base images or the previous production release. Keep required rollback images available through an intentional retention rule or a verified registry/artifact copy. Prune does not offer a general exact dry run, and some filter combinations cannot be previewed through image listing.

Adapt the policy to the machine

A disposable CI worker may tolerate aggressive cleanup between jobs; a shared builder may lose valuable cache and disrupt concurrent work. BuildKit cache has its own accounting and pruning controls. A developer workstation should preserve active experiments, while a production host needs the tested rollback image and application-state plan.

Avoid treating a fixed daily or weekly command as universally safe. Measure growth, establish who owns the objects, and choose a cadence that matches storage capacity and recovery needs.

Afterward, compare docker system df with the mount point's free bytes and inodes. Guance disk metrics can retain those trends. Whole-filesystem growth alone does not identify one image as the cause.

FAQ

Will Docker download deleted images again? A later launch may pull a missing image, depending on pull policy. That costs bandwidth and time and depends on registry availability. Mutable tags may resolve to different content, so keep immutable references when reproducibility matters.

Does local prune clean the registry? No. Registry retention, manifest deletion, and garbage collection are separate operations. Harbor and other registries have their own policies and version-specific requirements; use those supported workflows and preserve shared or referenced content.

Can I prune safely while keeping a stopped recovery container? Image-only pruning respects container references, but broader cleanup can remove the recovery container. Retaining that container is also not a substitute for backing up its mounted data.

See Docker image prune, system prune, and builder prune.