Docker Image Prune: Reclaim Your Disk Space

WHY IT EXISTS: Docker images are composed of layers. When you build or pull an updated image, Docker creates new layers, but the old, unreferenced ones remain on your disk. These "dangling" images consume significant space over time without providing any value, requiring a dedicated command to clean them up.

THE MENTAL MODEL: Think of docker image prune as a janitor for your local image cache. It safely sweeps up old image layers that no longer have a name tag and aren't being used by any container. It's a routine cleanup task to reclaim disk space without accidentally deleting an image you might need.

HOW IT WORKS: The command scans all images stored by your local Docker daemon. By default, it targets only "dangling" images—intermediate layers that have no tag and are not a parent of any tagged image. After identifying them, it will prompt you for confirmation before deletion. Using the --all or -a flag changes this behavior. With -a, it will remove all images that are not associated with at least one container, regardless of whether they are tagged or not.

WHEN TO USE IT: This command is most useful in development environments where you frequently build, test, and pull images, creating many intermediate and outdated versions. Running docker image prune periodically is a good maintenance habit to keep your disk usage in check. It is also commonly used in CI/CD pipelines to clean the build environment after a job completes.

WHEN NOT TO USE IT: Avoid using docker image prune -a if you want to keep pre-pulled, tagged images for future use, even if they aren't currently running in a container. Pruning them would force you to re-download or re-build them later. Be especially cautious with the -a flag on a shared machine where another user might need those cached images.

ONE CANONICAL EXAMPLE: To remove dangling images, run docker image prune. You will be shown what will be deleted and asked to confirm. To bypass this confirmation, use the force flag: docker image prune -f. For a more aggressive cleanup that removes all images not used by any container (not just dangling ones), use the all flag: docker image prune -a. This typically frees up much more space.