docker images and Image IDs

docker images and docker image ls show the images stored on your machine. This matters because Docker can only start containers from images it can resolve locally or pull from a registry, and image listings tell you which names, tags, IDs, sizes, and unused build results you already have.

The image ID is Docker’s local short identifier for image content. It is useful for inspection and cleanup, but tags and digests are usually better for repeatable human workflows.

Overview: How Image Listing Works

A Docker image is a read-only template made from stacked filesystem layers plus an image configuration document. It may contain an operating-system userland, application files, installed packages, labels, environment defaults, exposed-port metadata, and a default command. A container is different: it is an instance of an image with runtime settings and a thin writable layer on top. Removing a container does not remove its image, and removing an unused image does not remove a stopped container that still references it.

When you run docker image ls, the Docker CLI asks the Docker daemon for its local image metadata. The command does not contact Docker Hub just to list images. It reports what the daemon already knows in its local image store: repository names, tags, shortened image IDs, creation time, and virtual size. Docker Desktop on macOS and Windows stores those Linux image layers inside its managed Linux VM; native Linux stores them under Docker’s configured storage area.

The image ID shown in the table is a shortened form of the image’s content identifier. The full value is usually visible through docker image inspect as a string beginning with sha256:. You can often use a short prefix of an ID in commands, as long as it uniquely identifies one local image. If two images share the same underlying content, they can show the same image ID under different tags. That is not duplication; it means multiple names point to the same image object.

Tags are mutable labels, such as nginx:1.27-alpine or redis:7.2-alpine. The tag is convenient, but it is not the same as the content. A publisher can move a tag to a newer image later. A digest, such as nginx@sha256:..., identifies exact registry content more strongly. Local image listings show image IDs by default; they show digests only when you request them or when the digest is known from a pull.

Image size in docker image ls can also surprise beginners. The listed size is the image’s virtual size, not always the extra disk space that would be freed by deleting it. Layers are content-addressed and shared. If node:20-alpine and your own my-api:1.0 share base layers, Docker stores those shared layers once.

Syntax

The modern command is docker image ls. The older alias docker images still works and is common in examples, but the image subcommand form fits the current Docker CLI style.

docker image ls [OPTIONS] [REPOSITORY[:TAG]]
docker images [OPTIONS] [REPOSITORY[:TAG]]
Option or column Meaning
REPOSITORY The image name, such as nginx, alpine, or my-api.
TAG A label under a repository, such as 1.27-alpine. If you omit a tag in many Docker commands, Docker commonly assumes latest, which is a moving target.
IMAGE ID A shortened local content identifier. It can be used in commands when the prefix is unique.
CREATED When the image configuration was created by the publisher or builder, not necessarily when you pulled it.
SIZE The image’s virtual size. Shared layers mean actual reclaimable disk space may be lower.
--all or -a Shows intermediate images as well as the normal top-level images.
--digests Adds a DIGEST column when Docker knows the registry digest for the image.
--filter or -f Filters the list, for example dangling=true or reference=nginx:*.
--format Prints selected fields using a Go template. Useful for scripts and focused reports.
--no-trunc Shows full-length IDs instead of shortened IDs.

Examples

Example 1: Pull and List a Specific Image

docker pull nginx:1.27-alpine
docker image ls nginx:1.27-alpine

Output:

1.27-alpine: Pulling from library/nginx
Digest: sha256:1111222233334444example
Status: Downloaded newer image for nginx:1.27-alpine
REPOSITORY   TAG           IMAGE ID       CREATED       SIZE
nginx        1.27-alpine   4c84c57db0b7   2 weeks ago   48MB

The first command resolves the tag through a registry, downloads missing layers, and records metadata in the local image store. The second command lists only the matching repository and tag. Your digest, image ID, age, and size may differ because images are updated and Docker pulls the platform-specific image for your machine.

Example 2: See Tags, IDs, and Digests Together

docker image ls --digests nginx

Output:

REPOSITORY   TAG           DIGEST                         IMAGE ID       CREATED       SIZE
nginx        1.27-alpine   sha256:1111222233334444example  4c84c57db0b7   2 weeks ago   48MB
nginx        stable-alpine sha256:aaaabbbbccccddddexample  4c84c57db0b7   2 weeks ago   48MB

This output shows an important idea: different tags can point to the same local image ID. In that case Docker is not storing two full copies. It is storing one image object with more than one name. The digest column is registry-oriented and may appear as <none> for images you built locally or for images whose digest Docker did not record.

Example 3: Filter and Format Image Output

docker image ls --filter "reference=nginx:*" --format "table {{.Repository}}\t{{.Tag}}\t{{.ID}}\t{{.Size}}"

Output:

REPOSITORY   TAG           IMAGE ID       SIZE
nginx        1.27-alpine   4c84c57db0b7   48MB
nginx        stable-alpine 4c84c57db0b7   48MB

The filter keeps only image references matching nginx:*. The format string prints a compact table with the fields you selected. This is useful in scripts, but use names and full tags when a human will read the command later.

Example 4: Inspect the Full Image ID

docker image inspect nginx:1.27-alpine --format "{{.Id}}"

Output:

sha256:4c84c57db0b76040d40f0c9f7f902c0bexample

docker image ls shortens the ID for readability. docker image inspect can show the full identifier and much more metadata, including labels, environment defaults, architecture, exposed ports, layer history, and the configured command.

How It Works Step by Step

  1. You type docker image ls. The Docker CLI parses the command and sends an API request to the Docker daemon.
  2. The daemon reads its local image metadata. It does not need to start containers or contact a registry for a normal list operation.
  3. Docker groups local image references by repository and tag. Multiple references can point at the same image ID.
  4. For each row, Docker prints a shortened ID, the image configuration creation time, and virtual size.
  5. If you add --digests, Docker includes known registry digest metadata. Locally built images often do not have registry digests until they are pushed or pulled by digest.
  6. If you add --filter, filtering happens before output formatting. If you add --format, Docker renders only the fields requested by the template.

Listing images is read-only. It does not remove anything and it does not prove an image is unused. A stopped container can still reference an image. Before cleanup, check containers with docker container ls --all or use Docker’s prune commands deliberately.

Common Mistakes

Assuming the Image ID Is the Registry Digest

docker image ls --digests nginx

The IMAGE ID column and the DIGEST column are related to content identity, but they are not the same display value. The image ID identifies the local image configuration. The digest identifies registry content for a named image reference. For reproducible deployment, a digest-pinned reference is stronger than copying a short local image ID into documentation.

Deleting by Short ID Without Checking What It Matches

docker image rm 4c84c57db0b7

This command is valid, but it may remove every tag that points to that image ID if no containers still need it. Before deleting by ID, list matching rows and understand whether several repository tags share the same ID. A safer human habit is to remove a specific reference first:

docker image rm nginx:stable-alpine

Thinking Always Means Trash

docker image ls --filter "dangling=true"

Dangling images have no repository tag, often displayed as <none>. They are commonly old build results after retagging, but do not blindly remove things on a shared development machine. Check whether a stopped container or a build workflow still depends on the image before pruning aggressively.

Using latest as an Inventory Strategy

docker pull redis:latest
docker image ls redis

latest is just a tag. It does not mean newest patch, safest release, or same content next month. Prefer tested, specific tags such as redis:7.2-alpine, and use digests for strict production reproducibility.

Best Practices

  • Use docker image ls in new documentation; recognize docker images as a working alias.
  • List by repository and tag when you are checking one image, for example docker image ls nginx:1.27-alpine.
  • Use --digests when you need to connect local images back to exact registry content.
  • Use docker image inspect when the shortened ID or table columns are not enough.
  • Prefer specific tags over latest. Tags can move, so production systems should pin tested tags or digests.
  • Be careful deleting by image ID because multiple tags can share one ID.
  • Remember that image size is virtual size. Shared layers reduce actual disk usage and actual reclaimed space.
  • Before cleanup, check containers with docker container ls --all; containers can still reference images even when stopped.
  • Use --format for scripts instead of parsing column spacing from the default table.

Practice Exercises

  1. Pull alpine:3.20 and nginx:1.27-alpine, then list only the Nginx image. Expected end state: your command shows one row for nginx with tag 1.27-alpine.
  2. Run docker image ls --digests and compare the IMAGE ID column with the DIGEST column. Hint: they are different identifiers used in different contexts.
  3. Use --format to print only repository, tag, ID, and size for images whose reference starts with nginx:. Expected end state: a compact table suitable for a script or report.

Summary

  • docker image ls lists images stored in the local Docker daemon; docker images is its older alias.
  • An image is a read-only layered template. A container is a runtime instance with a writable layer.
  • The IMAGE ID column is a shortened local content identifier, and several tags can share one ID.
  • Tags are mutable names. Digests are stronger identifiers for exact registry content.
  • --digests, --filter, --format, and --no-trunc make image listings more precise.
  • Do not assume <none> images or shared IDs are safe to delete without checking containers and references.
  • Use specific tags or digests for repeatable work instead of depending on latest.