Filter Your Local Images with docker image ls

Before you clean up, deploy or debug anything on a Docker host, you need to know what is actually sitting there, and docker image ls tells you. You will finish with a reliable way to inspect the images already stored on a host, select an exact repository and tag, and produce output that is safe to read or hand to another tool. The examples use Docker CLI package version 5:29.8.1-1~ubuntu.24.04~noble, reporting Docker 29.8.1 on this machine. Allow about ten minutes.

You need: the Docker CLI and access to a daemon with at least one local image.
What it will not touch: these commands only inspect state. They do not pull, tag, remove or otherwise change an image, so they normally need no elevated privileges. If your installation requires sudo, add it consistently, but do not use it to hide a socket permission problem before checking that problem.

1. Confirm the installed command

Start by checking which executable and package version will answer your query. This is an ordinary read-only check:

$ command -v docker
/usr/bin/docker
$ docker --version
Docker version 29.8.1, build 4a63305
$ dpkg-query -W -f='${Package} ${Version}\n' docker-ce-cli
docker-ce-cli 5:29.8.1-1~ubuntu.24.04~noble

The command here is docker image ls, with the shorter historical spelling docker images also documented by Docker. Use the subcommand form in new scripts because it makes clear you are listing images, not containers.

Checkpoint: If docker --version fails, stop here and install or repair the CLI through your normal system process. If the CLI cannot connect to the daemon, fix the daemon or socket access first; changing listing options will not fix that error.

2. List the images visible to the daemon

Run the default listing:

$ docker image ls
REPOSITORY          TAG       IMAGE ID       CREATED        SIZE
parish              latest    27d367436234   7 hours ago    53.5MB
orbit               latest    68af45489e44   19 hours ago   77.9MB
orbit               v0.3.0    68af45489e44   19 hours ago   77.9MB

Your rows will differ. The columns are repository name, tag, shortened image ID, relative creation time and virtual size. This is a local inventory, not a registry search. An image can appear more than once when several tags or repository names point at the same image ID: in the example, two orbit tags share one image.

Intermediate build layers and dangling images are hidden by default. Show them when investigating a build or disk usage:

$ docker image ls --all

Do not read <none> rows as automatically safe to delete: a build or container workflow may still reference them. Listing is harmless, but cleanup is a separate operation that needs an explicit review.

3. Match a repository or an exact tag

Pass a repository name to see every local tag in that repository:

$ docker image ls orbit
REPOSITORY   TAG      IMAGE ID       CREATED        SIZE
orbit        latest   68af45489e44   19 hours ago   77.9MB
orbit        v0.3.0   68af45489e44   19 hours ago   77.9MB

Pass both repository and tag to narrow the result to that exact reference:

$ docker image ls orbit:v0.3.0
REPOSITORY   TAG      IMAGE ID       CREATED        SIZE
orbit        v0.3.0   68af45489e44   19 hours ago   77.9MB

The repository argument is an exact match: docker image ls noe will not find orbit or any other name it only partially matches. An empty table means the reference is not present locally, not that the name is invalid in a registry. Check spelling, tag and the daemon context before trying a pull.

Checkpoint: Verify the reference you plan to use before copying an image ID into another command:

$ docker image ls --quiet orbit:v0.3.0
68af45489e44

--quiet or -q prints only shortened IDs. It is useful for inspection and controlled pipelines, but do not assume a short ID is a permanent external identifier.

4. Get full IDs and digests when identity matters

The normal table shortens IDs to fit the terminal. Ask for the full content ID when recording an image or comparing hosts:

$ docker image ls --no-trunc orbit:v0.3.0
REPOSITORY   TAG      IMAGE ID                                                                  CREATED        SIZE
orbit        v0.3.0  sha256:68af45489e4429d0d02e29ea7471a334a99ab2148fc1b44884b6d61d3d920cbc   19 hours ago   77.9MB

Use --digests to add registry content digests where Docker has one:

$ docker image ls --digests orbit
REPOSITORY   TAG      DIGEST   IMAGE ID       CREATED        SIZE
orbit        v0.3.0   <none>   68af45489e44   19 hours ago   77.9MB

A local image showing <none> for its digest is telling you about the local record, not handing you a digest to invent. If you need a registry digest, inspect the result of the pull or push workflow and keep the complete value.

5. Filter the list without deleting anything

Filters use key=value. The installed command documents filters for dangling status, labels, creation time and image references. Find dangling images:

$ docker image ls --filter 'dangling=true'
REPOSITORY   TAG       IMAGE ID       CREATED        SIZE
<none>       <none>   123456789abc   3 days ago     12.4MB

Use a reference pattern for a name-based review:

$ docker image ls --filter 'reference=orbit:*'

Creation filters accept another image reference or ID as their boundary:

$ docker image ls --filter 'before=orbit:v0.3.0'
$ docker image ls --filter 'since=orbit:v0.3.0'

Warning: run the filtered listing first and review every row before you turn its output into an automatic removal command. Removing images can break a later deployment, and an image in use by a container may be protected only by a warning. If cleanup is genuinely intended, use the separate image removal or prune workflow, confirm the target set again, and make sure you have a rebuild or registry recovery path. Nothing in this guide changes state, so there is nothing to undo here.

6. Produce stable output for scripts

Human-oriented columns change width with names and terminal size. Use a custom format when another command needs selected fields:

$ docker image ls --format '{{.Repository}}:{{.Tag}} {{.ID}} {{.Size}}'
parish:latest 27d367436234 53.5MB
orbit:latest 68af45489e44 77.9MB

Available template fields include .ID, .Repository, .Tag, .CreatedSince, .CreatedAt and .Size. Use the table directive for headings:

$ docker image ls --format 'table {{.ID}}\t{{.Repository}}\t{{.Tag}}'
IMAGE ID       REPOSITORY   TAG
27d367436234   parish       latest
68af45489e44   orbit        latest

For machine-readable records, the documented json format emits one JSON object per image:

$ docker image ls --format json | head -n 1
{"Containers":"1","CreatedAt":"2026-09-22 23:02:35 +0100 BST","CreatedSince":"7 hours ago","Digest":"\u003cnone\u003e","ID":"27d367436234","Repository":"parish","Size":"53.5MB","Tag":"latest"}

Do not parse the display table with tools that depend on fixed column positions. Prefer a format template or JSON, and remember a JSON line contains display fields such as a human-readable size, not a promise that the image occupies exactly that amount of unique disk space.

Common traps

An empty result has several causes. An exact-name mismatch, a missing tag, a filter excluding every row, or a different Docker context. Rerun unfiltered first, then try the full repository and tag. If the unfiltered command cannot reach the daemon, inspect docker context show and your socket permissions without changing them.
Size is not reclaimable space. Parent layers can be shared by several images, and tags are references rather than independent copies. Do not treat a repeated image ID as duplicate storage, and do not treat a different tag as a different image until the ID or digest proves it.
The experimental --tree option is available in this release for multi-platform image trees, but it is not needed for ordinary local inventory. Keep scripts on the documented table, template or JSON forms unless you have deliberately chosen to depend on that experimental output.

Done means

Confirmed the CLI. You checked the Docker CLI and package version in use.
Told local from remote. You can distinguish local image inventory from a registry lookup.
Matched precisely. You can list all tags for a repository and match an exact repository and tag.
Used the right flags. You know when to reach for --all, --no-trunc, --digests and --quiet.
Filtered without deleting. You reviewed filters without turning them into an unexamined deletion command.
Scripted safely. Your scripts use a format template or JSON rather than scraping table spacing.