Listing local images in Docker - Deep Dive

Overview - Listing local images

What is it?

Listing local images means showing all the Docker images stored on your computer. Docker images are like blueprints for containers, which are small, isolated environments for running software. This command helps you see what images you have ready to use or share. It is a simple way to manage and organize your Docker images.

Why it matters

Without the ability to list local images, you would not know what images are available on your machine. This would make it hard to reuse images, clean up space, or understand what software versions you have. It helps avoid confusion and wasted storage by showing exactly what is stored locally.

Where it fits

Before learning to list local images, you should understand what Docker images and containers are. After this, you can learn how to manage images by removing, tagging, or pushing them to remote repositories. Listing images is a basic but essential step in Docker image management.

Mental Model

Core Idea

Listing local images is like opening your photo album to see all the pictures you have saved on your device.

Think of it like...

Imagine your computer is a photo album and Docker images are photos inside it. Listing local images is like flipping through the album to see all the photos you have stored, so you know what memories (images) are available to look at or share.

┌─────────────────────────────┐
│       Local Docker Images    │
├─────────────┬───────────────┤
│ IMAGE ID    │ IMAGE NAME    │
├─────────────┼───────────────┤
│ abc123def456│ ubuntu:22.04  │
│ def789abc012│ nginx:latest  │
│ 123abc456def│ myapp:v1      │
└─────────────┴───────────────┘

Build-Up - 7 Steps

1

Foundation

What are Docker images?

Concept: Understanding what Docker images are and why they matter.

Docker images are read-only templates that contain everything needed to run a piece of software, including code, libraries, and settings. They are like recipes for creating containers, which are running instances of these images.

Result

You know that images are the starting point for running software in Docker.

Understanding images as blueprints helps you see why managing them is important before running containers.

2

Foundation

How Docker stores images locally

Concept: Learn where and how Docker keeps images on your computer.

Docker stores images in a local storage area called the Docker image cache. This cache holds all the images you have downloaded or built, so Docker can quickly create containers from them without needing to fetch them again.

Result

You realize that images are saved locally and can be reused multiple times.

Knowing that images are cached locally explains why listing them helps manage disk space and reuse.

3

Intermediate

Using the docker images command

🤔Before reading on: do you think 'docker images' shows running containers or stored images? Commit to your answer.

Concept: Learn the basic command to list all local Docker images.

The command 'docker images' lists all images stored locally. It shows columns like REPOSITORY (image name), TAG (version), IMAGE ID (unique identifier), CREATED (when image was made), and SIZE (disk space used). Example: $ docker images REPOSITORY TAG IMAGE ID CREATED SIZE ubuntu 22.04 abc123def456 2 weeks ago 72MB nginx latest def789abc012 3 weeks ago 133MB

Result

You see a clear list of all local images with useful details.

Knowing this command is the foundation for managing images and understanding what is available locally.

4

Intermediate

Filtering images with options

🤔Before reading on: do you think you can list images by name or size using options? Commit to your answer.

Concept: Learn how to filter or format the list of images using command options.

You can use options like: - 'docker images ' to list images matching a name. - '--filter' to filter by criteria like dangling images (unused). - '--format' to customize output. Example: $ docker images nginx Only images with 'nginx' in the name show up. $ docker images --filter dangling=true Shows images not tagged or used by containers.

Result

You get a focused list of images matching your criteria.

Filtering helps you find specific images quickly and clean up unused ones.

5

Intermediate

Understanding image tags and IDs

Concept: Learn the difference between image names, tags, and IDs in the listing.

Each image has: - A REPOSITORY name (like 'ubuntu') - A TAG (like '22.04' or 'latest') to specify versions - An IMAGE ID, a unique short hash Tags help you pick versions, while IDs uniquely identify images even if names change.

Result

You can correctly identify and select images by name, tag, or ID.

Knowing these parts prevents mistakes like using the wrong image version.

6

Advanced

Listing images with JSON output

🤔Before reading on: do you think Docker can output image lists in JSON format? Commit to your answer.

Concept: Learn how to get image listings in JSON for automation or scripts.

Docker supports the '--format' option with Go templates to output JSON-like data. Example: $ docker images --format '{{json .}}' Outputs each image as a JSON object, useful for scripts. You can combine this with tools like jq to process image data programmatically.

Result

You can automate image management by parsing JSON output.

Understanding JSON output enables integration with other tools and automation pipelines.

7

Expert

How image layers affect listing and storage

🤔Before reading on: do you think each image is stored fully or shares parts with others? Commit to your answer.

Concept: Learn that images are made of layers shared across images, affecting storage and listing.

Docker images are built from layers stacked on top of each other. Many images share common layers (like the base OS). When you list images, you see each image as a whole, but under the hood, layers are reused to save space. This means deleting one image might not free all space if layers are shared. Understanding layers helps explain why some images appear similar and why storage behaves as it does.

Result

You grasp the efficiency of Docker's storage and the complexity behind image management.

Knowing about layers prevents confusion about disk usage and image deletion effects.

Under the Hood

Docker images are stored as a series of read-only layers. Each layer represents a set of filesystem changes. When you list images, Docker queries its local image store, which tracks metadata about each image, including its layers, tags, and IDs. The listing command reads this metadata and presents a summary to the user. Layers are shared between images to save space, so the listing shows images as distinct entities but they may share underlying data.

Why designed this way?

This layered design was chosen to optimize storage and speed. Instead of storing full copies of each image, Docker stores only differences in layers. This reduces disk usage and speeds up downloads and builds. The listing command abstracts this complexity, showing users simple image names and tags, hiding the layered internals for ease of use.

┌───────────────┐
│ Docker Image  │
│  ┌─────────┐  │
│  │ Layer 3 │  │
│  ├─────────┤  │
│  │ Layer 2 │  │
│  ├─────────┤  │
│  │ Layer 1 │  │
│  └─────────┘  │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Local Image   │
│ Metadata:     │
│ - Name        │
│ - Tag         │
│ - Image ID    │
│ - Layer refs  │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does 'docker images' show running containers? Commit yes or no before reading on.

Common Belief: Many think 'docker images' lists running containers.

Reality: 'docker images' only lists stored images, not running containers. Running containers are shown by 'docker ps'.

Why it matters: Confusing images with containers can lead to wrong commands and misunderstanding of Docker's state.

Quick: Does deleting an image always free all its disk space? Commit yes or no before reading on.

Common Belief: Deleting an image always frees all the disk space it used.

Reality: Because images share layers, deleting one image may not free all space if layers are used by other images.

Why it matters: Assuming full space is freed can cause unexpected disk usage and confusion during cleanup.

Quick: Can you list images by partial name with 'docker images'? Commit yes or no before reading on.

Common Belief: You cannot filter images by partial names using 'docker images'.

Reality: You can specify partial names or use filters to narrow down the list.

Why it matters: Not knowing filtering options slows down image management and cleanup.

Quick: Does the IMAGE ID change if you retag an image? Commit yes or no before reading on.

Common Belief: Retagging an image changes its IMAGE ID.

Reality: Retagging only adds or changes the tag; the IMAGE ID remains the same.

Why it matters: Misunderstanding this can cause confusion about image identity and version control.

Expert Zone

1

Listing images does not show dangling layers; these require separate commands to identify and clean.

2

The IMAGE ID shown is a shortened hash; the full ID is longer and used internally for precise identification.

3

Using '--format' with Go templates allows complex custom outputs, enabling integration with CI/CD pipelines.

When NOT to use

Listing local images is not useful when you want to see running containers or remote images. For running containers, use 'docker ps'. For remote images, use registry commands or web interfaces.

Production Patterns

In production, teams automate image listing combined with pruning unused images to save disk space. They also script JSON output parsing to integrate with monitoring and deployment tools.

Connections

Container lifecycle management

Builds-on

Knowing what images exist locally helps manage container creation, updates, and cleanup effectively.

Version control systems

Similar pattern

Docker image tags and IDs function like commits and branches, helping track versions and changes.

Library cataloging systems

Analogous process

Listing images is like cataloging books in a library, enabling quick lookup and management of resources.

Common Pitfalls

#1 Trying to list running containers with 'docker images'.

Wrong approach:

$ docker images
(Expecting to see running containers)

Correct approach:

$ docker ps
(Shows running containers)

Root cause:

Confusing images (blueprints) with containers (running instances).

#2 Assuming deleting an image frees all disk space immediately.

Wrong approach:

$ docker rmi ubuntu:22.04
(Expecting full space freed)

Correct approach:

$ docker image prune
(Removes unused layers and frees space)

Root cause:

Not understanding shared layers and dangling images.

#3 Using 'docker images' without filters to find a specific image.

Wrong approach:

$ docker images
(Scrolling through long list)

Correct approach:

$ docker images nginx
(Shows only nginx images)

Root cause:

Not knowing filtering options to narrow results.

Key Takeaways

Docker images are stored locally as layered blueprints for containers.

The 'docker images' command lists all local images with details like name, tag, and ID.

Images share layers to save space, so deleting one image may not free all disk space.

Filtering and formatting options help manage and automate image listings effectively.

Understanding the difference between images and containers prevents common Docker mistakes.