19.1.5.3 Rmi Dangling Cleanup

Dangling cleanup refers to the process of identifying and removing Docker images that have no tag and are not referenced by any container or other image. These images accumulate naturally on any active development or build machine and consume disk space without serving any ongoing purpose.

What Makes an Image Dangling

An image becomes dangling when its tag is reassigned to a newer build. Consider this sequence:

docker build -t myapp:latest .   # build 1 → creates image A, tagged myapp:latest
docker build -t myapp:latest .   # build 2 → creates image B, tagged myapp:latest

After the second build, myapp:latest now points to image B. Image A no longer has any tag pointing to it. It exists in the local store but is invisible in a normal docker images listing. This is a dangling image.

Dangling images are shown with repository and tag both set to <none>:

docker images

REPOSITORY   TAG       IMAGE ID       CREATED        SIZE
myapp        latest    b2c3d4e5f6a7   5 minutes ago  230MB
<none>       <none>    a1b2c3d4e5f6   1 hour ago     229MB
<none>       <none>    9e8d7c6b5a4f   3 hours ago    215MB

Identifying Dangling Images

Docker supports filtering images by the dangling attribute:

docker images -f "dangling=true"

Output:

REPOSITORY   TAG       IMAGE ID       CREATED        SIZE
<none>       <none>    a1b2c3d4e5f6   1 hour ago     229MB
<none>       <none>    9e8d7c6b5a4f   3 hours ago    215MB

To retrieve only the IDs (useful for scripting):

docker images -f "dangling=true" -q

a1b2c3d4e5f6
9e8d7c6b5a4f

Removing Dangling Images with rmi

The IDs returned by the filter can be passed directly to docker rmi:

docker rmi $(docker images -f "dangling=true" -q)

This is equivalent to running docker rmi a1b2c3d4e5f6 9e8d7c6b5a4f and removes all dangling images in one invocation.

On Windows PowerShell:

docker rmi $(docker images -f "dangling=true" -q)

Or using a loop for more control:

docker images -f "dangling=true" -q | ForEach-Object { docker rmi $_ }

Using docker image prune

The more idiomatic way to clean dangling images is:

docker image prune

Docker displays a confirmation prompt listing how much space will be reclaimed:

WARNING! This will remove all dangling images.
Are you sure you want to continue? [y/N] y
Deleted Images:
untagged: <none>@sha256:a1b2c3...
deleted: sha256:a1b2c3d4e5f6...
deleted: sha256:...

Total reclaimed space: 229.3MB

To skip the confirmation:

docker image prune -f

Dangling Cleanup in the Build Cycle

On active build machines, dangling images can accumulate rapidly — every docker build call that reuses a tag creates a new dangling image from the previous build.

Filtering by Time

To clean only dangling images older than a specific duration:

docker image prune --filter "until=24h"

This removes dangling images created more than 24 hours ago, preserving recent ones that might still be useful for debugging.

Dangling vs. Unused

It is important to distinguish between dangling and unused images:

docker image prune without -a only targets dangling images. Adding -a extends the operation to all images not referenced by any container, including tagged ones that simply have not been used to start a container.

Build Cache vs. Dangling Images

Build cache (used by docker build to speed up repeated builds) is separate from dangling images. The build cache is managed by docker builder prune, not docker image prune. Cleaning dangling images does not automatically clean the build cache.

To clean both:

docker image prune -f
docker builder prune -f

Or use the comprehensive system prune:

docker system prune

docker system prune removes stopped containers, dangling images, unused networks, and the build cache in a single command. Adding -a also removes unused tagged images.

Automating Dangling Cleanup

On developer machines where builds run frequently, a scheduled cleanup prevents disk exhaustion:

On Linux (cron job every night at 2 AM):

0 2 * * * docker image prune -f >> /var/log/docker-cleanup.log 2>&1

In a Makefile:

clean-images:
	docker image prune -f

In a CI post-build step:

docker image prune -f

Running cleanup at the end of every CI build keeps runner disk usage stable without requiring manual intervention.