From e2b27303cb9ecc90f433981bdccffcb15be3c870 Mon Sep 17 00:00:00 2001 From: Dean Chen <862469039@qq.com> Date: Thu, 6 Aug 2026 11:46:05 +0500 Subject: [PATCH] docs: clarify dangling=true vs dangling=false for docker images Explain that dangling means untagged leaves (:), and that dangling=false still includes repo: images, which often look \"untagged\" but are not dangling. Fixes #4159 Signed-off-by: Dean Chen <862469039@qq.com> --- docs/reference/commandline/image_ls.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/reference/commandline/image_ls.md b/docs/reference/commandline/image_ls.md index b600dd75bd21..dd8a7a4d4487 100644 --- a/docs/reference/commandline/image_ls.md +++ b/docs/reference/commandline/image_ls.md @@ -152,6 +152,17 @@ The currently supported filters are: #### Show untagged images (dangling) +The `dangling` filter is a boolean (`true` or `false`): + +- `dangling=true` — only **dangling** images: untagged leaves of the image + graph, shown as `:`. These appear when a new build retags an + image and leaves the previous ID without a repository or tag. +- `dangling=false` — every image that is **not** dangling. This still + includes normal tagged images, and it can also include images that keep a + repository name but have no tag (`myrepo:`). Those are untagged + references, not dangling images, so they appear for both + `dangling=false` and an unfiltered `docker images` listing. + ```console $ docker images --filter "dangling=true" @@ -164,9 +175,6 @@ REPOSITORY TAG IMAGE ID CREATED 511136ea3c5a 8 months ago 0 B ``` -This will display untagged images that are the leaves of the images tree (not -intermediary layers). These images occur when a new build of an image takes the -`repo:tag` away from the image ID, leaving it as `:` or untagged. A warning will be issued if trying to remove an image when a container is presently using it. By having this flag it allows for batch cleanup.