docker_unused_images
docker_unused_images removes the Docker images that no container uses,
running or stopped, as docker image prune does. It frees disk space on a
node whose old images fill it. remove says which images go: only those
without a name (dangling_images_only), or every image that no container
uses (every_image_no_container_uses).
An image is dangling when it has no name left: a pull of a tag that moved to
a newer image takes the tag from the old image, and a build that reuses a
tag does the same. docker_image pulls images and
removes none.
Set up
Docker must be installed on the node, and the node's Docker daemon must be
running, as for docker_image.
Inputs
remove(dangling_images_onlyorevery_image_no_container_uses; required): no default: dangling_images_only removes the images that have no name left, such as the one a pull of a moved tag replaced (docker image prune); every_image_no_container_uses also removes named images that no container uses (docker image prune --all), such as a previous version that a deploy keeps for a quick rollback
Outputs
The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.
statuschangereasonvalue.removed_imagesvalue.freed_bytes
What a dryrun reports
Removes nothing; lists the images that a run would remove, each with its image_id, names, and size_bytes, as docker image inspect reports them; freed_bytes is null, because only the Docker daemon's removal says what it frees; unchanged when no image qualifies; not_checked while the docker command or the Docker daemon is missing.
Retries and time limits
Bounded automatic retries by default; retry: false turns them off.
The node task takes the time limits time_limit and time_limit_per_try; without them, the project's node_task_defaults apply. mmx describe-module task describes the settings every node task accepts.
Examples
Remove the images that lost their names
- docker_unused_images:
remove: dangling_images_only
On the node, MMX lists the images without a name (docker image ls --filter dangling=true) and leaves out each one that a container uses,
running or stopped (docker container inspect). If at least one unused,
unnamed image remains in the list, MMX asks the node's Docker daemon to
remove unused, unnamed images. MMX sends the request that
docker image prune sends. MMX reports the images the daemon deleted and
the bytes the daemon freed:
changed — removed 3 images from the node's Docker images and freed 512.4 MiB (537291776 bytes): sha256:0e5c...; sha256:9a1f...; sha256:44d2...
value.removed_images lists each image with its image_id, its names,
and its size_bytes as docker image inspect reports it, and
value.freed_bytes holds the bytes that the daemon freed. When no image
qualifies, the node task is unchanged and asks the daemon nothing.
Every image that no container uses
- docker_unused_images:
remove: every_image_no_container_uses
The example node task also removes named images that no container uses,
like docker image prune --all. For example, the node task removes
registry.example.com/shop/web:2.3 after the containers moved to 2.4.
Running the example node task deletes a previous image kept for a quick
rollback when no container uses the previous image. The
every_image_no_container_uses choice deletes the previous version during
the node task's run, after containers stop using the previous image. A
rollback must then pull the previous image again. Use
dangling_images_only on such a node, or remove the images only after the
new version has proved itself.
How it works
- The removal is the daemon's own: MMX sends
POST /images/prunewith the filterdangling=true, ordangling=falsefor every image, on the daemon's Unix socket, which is whatdocker image prunesends. The daemon's answer, in JSON, gives the bytes it freed, counted by layer, so a layer that a remaining image shares is not counted. Which of the listed images went, MMX reads fromdocker image lsafterwards. - Images without a name. The containerd image store, which a new
installation of Docker 29 uses, keeps a record without a name for an
image that a pull of a moved tag replaced, also when other records still
give the same image names;
docker image ls --filter dangling=truelists it. Prune removes only that record and the image stays, so the node task leaves such an image out. - Images that a container's name names. The containerd image store also
keeps an image whose name is the one a container was created with, such
as
registry.example.com/shop/web:2.4after a pull moved that tag to a newer image while the container still runs the older one. The node task leaves such an image out there too; the classic image store removes it. - A dryrun removes nothing. It lists the images that a run would remove,
with their sizes as
docker image inspectreports them, which count shared layers in full. Only the daemon's removal says what it frees, sofreed_bytesisnullin a dryrun, and a later node task that reads the value is not checked. - Images from Docker's former builder. A build without BuildKit leaves unnamed parent images. The daemon removes them with the image that needed them, and keeps an image that a used image still needs, taking only its name. The result lists the images of the listing that went, and says when the daemon removed only names or images that the listing did not name.
Errors and what they mean
| The reason holds | What the error means, and what to do |
|---|---|
docker_unused_images.remove is required |
Validation requires remove; there is no default. |
the Docker daemon refused to remove unused images: a prune operation is already running |
Another Docker prune operation is running. Run the node task again when the Docker prune operation finishes. |
the docker command reaches the Docker daemon at ... |
MMX asks the daemon on a Unix socket of the node only. |
Tested on
Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10.
The suite tests/integration/docker_containers.py pulls images whose tags
move and leaves one image in use by a stopped container. The suite compares
the dryrun, the run, and docker image ls on the node with
dangling_images_only and every_image_no_container_uses. The suite covers
Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, and AlmaLinux 10. The
validation record has the latest results.
Why it works this way
removehas no default. Whether named images are removed determines whether a rollback image survives, so each node task must specify the removal choice throughremove.- The daemon's request, not the docker command's text.
docker image pruneprints its result as text and rounds the bytes; the daemon's answer is JSON with the exact bytes. freed_bytescounts layers, not images. The sum of the removed images' sizes would count every shared layer, which stays on disk.
This page is docs/reference/modules/docker_unused_images.md in the MMX repository.