From d9778d85ce380644b620bc9fbe2ebcaeed1f293f Mon Sep 17 00:00:00 2001 From: Dean Chen <862469039@qq.com> Date: Fri, 7 Aug 2026 11:51:37 +0500 Subject: [PATCH] docs: contrast image ls and image prune filter keys The two commands both take --filter but accept different keys; document that so people stop expecting until/reference/dangling to work on both. Fixes #3696 Signed-off-by: Dean Chen <862469039@qq.com> --- docs/reference/commandline/image_ls.md | 6 ++++++ docs/reference/commandline/image_prune.md | 4 ++++ 2 files changed, 10 insertions(+) diff --git a/docs/reference/commandline/image_ls.md b/docs/reference/commandline/image_ls.md index b600dd75bd21..1f97186eb7d9 100644 --- a/docs/reference/commandline/image_ls.md +++ b/docs/reference/commandline/image_ls.md @@ -150,6 +150,12 @@ The currently supported filters are: * since (`[:]`, `` or ``) - filter images created since given id or references * reference (pattern of an image reference) - filter images whose reference matches the specified pattern +These keys are **not** the same set as `docker image prune --filter`. Prune +supports `until` and `label` / `label!=...`, but not `dangling`, `before`, +`since`, or `reference`. Negative label filters (`label!=...`) work with prune +but not with `docker image ls`, so you cannot always preview prune matches with +`image ls`. See [docker image prune](image_prune.md#filter). + #### Show untagged images (dangling) ```console diff --git a/docs/reference/commandline/image_prune.md b/docs/reference/commandline/image_prune.md index 295cf3ea9f53..d50ed633fb2e 100644 --- a/docs/reference/commandline/image_prune.md +++ b/docs/reference/commandline/image_prune.md @@ -77,6 +77,10 @@ The currently supported filters are: * until (``) - only remove images created before given timestamp * label (`label=`, `label==`, `label!=`, or `label!==`) - only remove images with (or without, in case `label!=...` is used) the specified labels. +`docker image ls --filter` uses a different key set (`dangling`, `label`, +`before`, `since`, `reference`) and does not accept `until` or `label!=...`. +Do not assume the two commands share filter syntax. + The `until` filter can be Unix timestamps, date formatted timestamps, or Go duration strings supported by [ParseDuration](https://pkg.go.dev/time#ParseDuration) (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. Supported formats for date