Docker CLI images vs image

[sozercan]

Description

docker image ls (newer) and docker images ls (older) are different commands. This is very confusing for the user as it is easy to mistake images with image. Docker CLI does not provide any warnings.

$ docker images ls
REPOSITORY   TAG       IMAGE ID   CREATED   SIZE

$ docker image ls
REPOSITORY   TAG                                IMAGE ID       CREATED          SIZE
alpine       latest                             8ca4688f4f35   10 days ago      7.33MB
ubuntu       latest                             3565a89d9e81   2 weeks ago      77.8MB

$ docker version
Client:
 Version:           24.0.6-2

Server:
 Engine:
  Version:          24.0.6-4

[rafaelucena]

That happens because docker images is actually an alias of docker image ls, so, essentially, when you're running docker images ls what it's really doing is running docker image ls ls.

The effect is that it filters the images that have ls as part of it's names.

Example:

$ docker images node
REPOSITORY   TAG         IMAGE ID       CREATED        SIZE
node         18          cf58080ad70c   22 hours ago   1.09GB
node         18-alpine   59b532238836   2 weeks ago    177MB
node         14-alpine   0dac3dc27b1a   6 months ago   119MB

$ docker image ls node
REPOSITORY   TAG         IMAGE ID       CREATED        SIZE
node         18          cf58080ad70c   22 hours ago   1.09GB
node         18-alpine   59b532238836   2 weeks ago    177MB
node         14-alpine   0dac3dc27b1a   6 months ago   119MB

[thaJeztah]

Yes, this is a bit unfortunate, and definitely has confused others.

The docker images command was introduced when there were only "two" things that were managed by the CLI: containers and images;

• containers could be listed through docker ps and removed with docker rm
• images could be listed through docker images and removed with docker rmi, and docker images had a positional argument to filter.

This UX didn't scale well when other kind of objects (volumes, networks (and nodes, services, secrets, configs for swarm)) were introduced, so we switched to using docker <object> <command> syntax going forward (docker container ls (or docker container list), docker container rm, docker image ls, docker volume ls etc), but we could not remove the old commands because they were already widely used, so kept them as aliases.

We need to look if we can make handle these situations better; perhaps we need to deprecate the positional argument on docker images, and only allow --filter, or detect common mistakes where the search-term matches one of the subcommands for docker image (inspect, ls, rm etc.), and print a warning if those are used.

[thaJeztah]

/cc @jalonsogo

[devashishTaneja]

@thaJeztah / @rafaelucena Can I take up this issue?

[desmond3th]

@thaJeztah I'm ready to contribute. Should we tackle this issue like you suggested? Your thoughts?

[thaJeztah]

I'm not sure if there's a good solution for this. The only possible option would be to print a warning if the first positional argument would be any of the subcommands that are currently supported by docker image (build, history, import, inspect, load, list, ls, prune, pull, push, remove, rm, save, tag)