`docker image ls -f dangling=true` shows no images unless `-a` is also specified

[Emeraude998]

Description

According to the docker image ls documentation, the dangling filter is supposed to show untagged (dangling) images, and the examples use it without -a:

docker images --filter "dangling=true"

This is documented as “Show untagged images (dangling)”.[Image ls filter]

However, in practice, docker image ls -f dangling=true returns no images, even when there are known dangling images present. To see the dangling images, I have to add -a:

docker image ls -a -f dangling=true

This suggests that docker image ls first hides untagged images by default, and then applies the dangling=true filter on that already-filtered list, so there’s nothing left to match. This behavior seems related to the change noted in the Engine 29.0.0 [Engine 29.0.0 notes] release notes:

"docker image ls no longer shows untagged images by default if no --all flag is provided."

Reproduce

1. Build or pull an image, then create a dangling image (for example, by rebuilding an image with the same tag so the previous one becomes :).

2. Run:

docker image ls -f dangling=true

→ No images listed.

3. Run:

docker image ls -a -f dangling=true

→ Dangling images are listed.

Expected behavior

Either:

1. docker image ls -f dangling=true should list dangling images even without -a, matching the documentation examples, or

2. The documentation should be updated to reflect that -a is now required to see dangling images, and examples should use:

docker image ls -a --filter "dangling=true"

docker version

Client: Docker Engine - Community
 Version:           29.1.2
 API version:       1.52
 Go version:        go1.25.5
 Git commit:        890dcca
 Built:             Tue Dec  2 21:55:19 2025
 OS/Arch:           linux/amd64
 Context:           default

Server: Docker Engine - Community
 Engine:
  Version:          29.1.2
  API version:      1.52 (minimum version 1.44)
  Go version:       go1.25.5
  Git commit:       de45c2a
  Built:            Tue Dec  2 21:55:19 2025
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          v2.2.0
  GitCommit:        1c4457e00facac03ce1d75f7b6777a7a851e5c41
 runc:
  Version:          1.3.4
  GitCommit:        v1.3.4-0-gd6d73eb8
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

docker info

Client: Docker Engine - Community
 Version:    29.1.2
 Context:    default
 Debug Mode: false
 Plugins:
  buildx: Docker Buildx (Docker Inc.)
    Version:  v0.30.1
    Path:     /usr/libexec/docker/cli-plugins/docker-buildx
  compose: Docker Compose (Docker Inc.)
    Version:  v5.0.0
    Path:     /usr/libexec/docker/cli-plugins/docker-compose

Server:
 Containers: 6
  Running: 6
  Paused: 0
  Stopped: 0
 Images: 20
 Server Version: 29.1.2
 Storage Driver: overlay2
  Backing Filesystem: extfs
  Supports d_type: true
  Using metacopy: false
  Native Overlay Diff: true
  userxattr: false
 Logging Driver: json-file
 Cgroup Driver: systemd
 Cgroup Version: 2
 Plugins:
  Volume: local
  Network: bridge host ipvlan macvlan null overlay
  Log: awslogs fluentd gcplogs gelf journald json-file local splunk syslog
 CDI spec directories:
  /etc/cdi
  /var/run/cdi
 Swarm: inactive
 Runtimes: io.containerd.runc.v2 runc
 Default Runtime: runc
 Init Binary: docker-init
 containerd version: 1c4457e00facac03ce1d75f7b6777a7a851e5c41
 runc version: v1.3.4-0-gd6d73eb8
 init version: de40ad0
 Security Options:
  apparmor
  seccomp
   Profile: builtin
  cgroupns
 Kernel Version: 6.14.0-35-generic
 Operating System: Ubuntu 24.04.3 LTS
 OSType: linux
 Architecture: x86_64
 CPUs: 4
 Total Memory: 15.4GiB
 Name: Home-Assistant
 ID: 99a837b9-a3f2-4924-a5b7-7efe7560247d
 Docker Root Dir: /var/lib/docker
 Debug Mode: false
 Experimental: false
 Insecure Registries:
  127.0.0.0/8
  ::1/128
 Live Restore Enabled: false
 Firewall Backend: iptables

Additional Info

Request

Could you please:

• Confirm whether this behavior is intentional, and
• Either adjust the CLI behavior so -f dangling=true works without -a, or update the docs/examples to clarify that -a is required to see dangling images now?

Thanks!

[vvoland]

Thanks! This is not intentional and should be explicitly handled by this code:

https://github.com/vvoland/cli/blob/73aade19c102f671c7a3fdd3f46f68a777723fe3/cli/command/image/list.go#L110-L114

Looks like there's an issue with the logic of determining if the image is dangling under the graphdrivers.

I will open a PR with fix soon.