19.3.2.4 Prune Dangling Images

Dangling images are Docker images that have no tag and are not referenced by any container. They appear in docker images output with <none> in both the REPOSITORY and TAG columns, identified only by their SHA256 image ID. When docker system prune runs, removing dangling images is included in its default operation. They can also be removed independently using docker image prune.

How Dangling Images Are Created

A dangling image is produced whenever a new image displaces an existing image that had the same name and tag. The displacement breaks the tag's association with the old image, leaving it unnamed and untagged.

The most common cause is building an image with the same tag repeatedly during development or CI:

docker build -t my_app:latest .

Each time this command runs, the new image takes the my_app:latest tag. The previous my_app:latest image — which has no other tags — loses its tag and becomes dangling. If this process runs 20 times, 19 dangling images accumulate on the host.

Pulling an updated image with the same tag also creates a dangling image:

docker pull nginx:latest

If a previous version of nginx:latest exists locally and the registry has a newer version, pulling it moves the tag to the new image, leaving the old one dangling.

Identifying Dangling Images

docker images --filter dangling=true

This lists only dangling images:

REPOSITORY   TAG       IMAGE ID       CREATED         SIZE
<none>       <none>    abc123def456   2 days ago      512MB
<none>       <none>    def456abc789   5 days ago      487MB
<none>       <none>    789abc012def   1 week ago      498MB

The IMAGE ID is the only identifier available for dangling images. They can still be used to create containers by referencing their full SHA256 ID, but this is uncommon.

Pruning Dangling Images

As part of docker system prune:

docker system prune

Dangling images are included in the default cleanup. The command lists deleted image digests in the output:

Deleted Images:
deleted: sha256:abc123def456...
deleted: sha256:def456abc789...
untagged: sha256:789abc012def...

To prune only dangling images without affecting containers, volumes, or networks:

docker image prune

Docker prompts for confirmation:

WARNING! This will remove all dangling images.
Are you sure you want to continue? [y/N]

After confirmation:

Deleted Images:
deleted: sha256:abc123def456aabbccddeeff...

Total reclaimed space: 512MB

To skip the confirmation:

docker image prune --force

Dangling vs. Unused Images

Dangling images are a subset of the broader category of unused images:

• Dangling: No tag, no reference from any container.
• Unused: May be tagged, but not referenced by any running or stopped container.

docker image prune by default removes only dangling images. To also remove tagged images that no container is using:

docker image prune --all

The --all flag is more aggressive and is equivalent to the image portion of docker system prune --all.

Filtering Dangling Image Pruning

To remove only dangling images created or last used before a specific time:

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

This removes dangling images older than 72 hours, preserving recently built dangling images that may still be in use by in-flight containers or referenced by pending deployments.

To filter by label (removes only dangling images with the matching label):

docker image prune --filter "label=stage=build"

Impact on Disk Space

Dangling images can accumulate quickly on active build hosts. Each dangling image occupies space proportional to its unique layers — layers not shared with other images on the host. On a CI server that builds a 500MB application image 50 times per day, dangling images could accumulate at several hundred megabytes per day after accounting for shared base layers.

The UNIQUE SIZE column in docker system df -v output shows exactly how much disk space each dangling image contributes uniquely:

docker system df -v

Images with <none>:<none> in the REPOSITORY and TAG columns with high UNIQUE SIZE values represent the most impactful dangling images to remove.

Preventing Dangling Image Accumulation

On development machines, using multi-stage builds reduces the number of intermediate images left behind. In CI/CD pipelines, running docker image prune --force at the end of each build job ensures dangling images from that job are immediately removed. Using BuildKit with docker buildx build also results in fewer dangling intermediate images compared to the legacy builder.