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_only or every_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.

  • status
  • change
  • reason
  • value.removed_images
  • value.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/prune with the filter dangling=true, or dangling=false for every image, on the daemon's Unix socket, which is what docker image prune sends. 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 from docker image ls afterwards.
  • 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=true lists 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.4 after 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 inspect reports them, which count shared layers in full. Only the daemon's removal says what it frees, so freed_bytes is null in 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

  • remove has no default. Whether named images are removed determines whether a rollback image survives, so each node task must specify the removal choice through remove.
  • The daemon's request, not the docker command's text. docker image prune prints its result as text and rounds the bytes; the daemon's answer is JSON with the exact bytes.
  • freed_bytes counts 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.