Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 111 ยท Images

Understanding Images

Understand what a Docker image really is: layers, the manifest and config, content-addressable IDs, tags vs. digests, official images and how to inspect them.

Every container starts from an image, and almost every Docker problem you will meet later (slow builds, huge downloads, "it changed under me", security alerts) comes down to how images work. Yet most beginners treat an image as a magic box with a name. In this lesson we open the box.

An image is a read-only, layered, content-addressed bundle: a stack of filesystem changes plus a small piece of configuration that says how to start a process from them. Once you understand each of those words, tags, digests, caching, registries and image sizes all become easy to reason about.

Image vs. container, once more

An image is the template; a container is a running (or stopped) instance of it. You can start any number of containers from one image, just as you can start any number of processes from one program file.

TEXT
                  docker run                    docker run
   image  โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ถ  container 1
 (read-only)      docker run
      โ”‚ โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ถ  container 2
      โ”‚
      โ””โ”€ shared by all containers; each container adds
         its own thin writable layer on top

The image never changes while containers run. Whatever a container writes goes into its own writable layer, and disappears with the container (unless you use a volume). To "change an image", you build a new one.

What is inside an image

An image consists of three kinds of things:

  1. Layers. Each layer is an archive (a tar file) of files that were added, changed or deleted by one step of the build. Stacked in order, they form the complete root filesystem of the container: /bin, /etc, your application, and so on.
  2. A config. A JSON document with the metadata Docker needs to run it: default command (CMD), entrypoint, environment variables, working directory, user, exposed ports, labels, and the list of layer IDs.
  3. A manifest. A JSON document that lists the config and the layers by their digests. This is what a registry stores and what docker pull downloads first.

We can look at all three for the tiny alpine image. First, the registry-side manifest (shortened with ...):

CONSOLE
$ docker buildx imagetools inspect --raw alpine@sha256:c26612752c78...
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "digest": "sha256:b92841763c5c...",
    "size": 611
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:7b229517ed22...",
      "size": 3853109
    }
  ],
  ...
}

The manifest points to one config (611 bytes of JSON) and one layer, a gzip-compressed tar of about 3.85 MB. These formats follow the OCI image specification, the open standard that Docker, Podman, containerd and Kubernetes all share, so an image built with one tool runs in any other.

Layers

Alpine has a single layer because the whole Linux userland is one tarball. Most images have more. docker history shows the steps that created each layer, newest first:

CONSOLE
$ docker history alpine
IMAGE          CREATED        CREATED BY                                      SIZE      COMMENT
be2656061b53   40 hours ago   CMD ["/bin/sh"]                                 0B        buildkit.dockerfile.v0
<missing>      40 hours ago   ADD alpine-minirootfs-3.24.3-x86_64.tar.gz /โ€ฆ   9.08MB    buildkit.dockerfile.v0

ADD ... tar.gz created the one real layer (9.08 MB unpacked, which is why the registry's compressed copy was only 3.85 MB); CMD only adds metadata, so its size is 0 B. <missing> is not an error: it means the intermediate step is not an image you pulled by its own ID. We study layers and the union filesystem in depth in Layers and the Union Filesystem.

You can also ask for the list of layer IDs of any local image:

CONSOLE
$ docker image inspect alpine -f '{{json .RootFS}}'
{"Type":"layers","Layers":["sha256:75c137aedfb2760f88629236cb7b797630aed0c3d91d626d1d1bb694878fc2ba"]}

These layer IDs differ from the manifest's digest above because they are hashes of the uncompressed content (called "diff IDs"), while the manifest's digests are hashes of the compressed archive that travels over the network.

The config

The part of the config that matters most day to day is what docker image inspect reports under Config:

CONSOLE
$ docker image inspect nginx:alpine -f '{{json .Config.ExposedPorts}} {{.Config.Entrypoint}} {{.Config.Cmd}}'
{"80/tcp":{}} [/docker-entrypoint.sh] [nginx -g daemon off;]
$ docker image inspect nginx:alpine -f '{{json .Config.Labels}}'
{"maintainer":"NGINX Docker Maintainers <[email protected]>"}

That is why docker run nginx:alpine knows what to execute and which port the image documents: both are written in the image. docker run arguments can override most of it (CMD and ENTRYPOINT explains how).

Content addressing: names derived from content

Docker identifies every blob (layer, config, manifest) by the SHA-256 hash of its bytes, written sha256:<64 hex characters>. This idea is called content-addressable storage, and it has big consequences:

  • Integrity. If a single bit changes, the hash changes. Docker verifies the hash after each download, so a corrupted or tampered layer is rejected.
  • Deduplication. Two images that contain the same layer have the same hash, so the layer is stored and downloaded once.
  • Immutability. You cannot change a blob without changing its name. A hash always refers to exactly the same content, forever.

Deduplication is easy to see. We built two small images on top of alpine; the second adds one more RUN line to the first. Their layer lists:

CONSOLE
$ docker image inspect tcd-img:1 -f '{{range .RootFS.Layers}}{{printf "%.19s" .}}{{"\n"}}{{end}}'
sha256:75c137aedfb2
sha256:4118d5c2ad5e
$ docker image inspect tcd-img:2 -f '{{range .RootFS.Layers}}{{printf "%.19s" .}}{{"\n"}}{{end}}'
sha256:75c137aedfb2
sha256:4118d5c2ad5e
sha256:3fc2dc6fb3ae

The first two layers are identical (same hashes), so image 2 only needs its own third layer. If you have ten images based on alpine, the alpine layer exists on disk once.

docker images therefore reports sizes that overlap: the "disk usage" of several images is not the sum of the rows, because shared layers are counted in each. docker system df shows the real total (The Docker CLI).

Image ID

Every local image has an image ID: in classic Docker it is the hash of the image config; with the containerd image store that Docker 29 uses by default, it is the digest of the top-level manifest (or index). You usually see its first 12 characters:

CONSOLE
$ docker images
IMAGE               ID             DISK USAGE   CONTENT SIZE   EXTRA
tcd-img:1           d3519136a227       12.9MB         3.86MB
tcd-img:2           5c3016ebc8d7         13MB         3.86MB
tcd-img:latest      5c3016ebc8d7         13MB         3.86MB

(Your IDs and sizes will differ.) Two things to read from this table. First, tcd-img:2 and tcd-img:latest have the same ID: they are two names for one image. Second, in current Docker versions the table has two size columns: DISK USAGE is what the image occupies unpacked on disk, and CONTENT SIZE is what was downloaded or would be pushed (compressed, shared blobs counted once). Older versions printed a single SIZE column.

Wherever Docker takes an image reference you can also give a unique prefix of the ID (docker run d3519136a227), but a name is easier to remember.

Names, tags and digests

A full image reference has up to four parts:

TEXT
docker.io / library / nginx : 1.27-alpine @ sha256:a1b2c3...
 registry   namespace  repo     tag             digest
  • The registry is where the image is stored. If you leave it out, Docker assumes Docker Hub (docker.io).
  • The namespace is the user or organization (library is the special namespace of Docker's official images; nginx is shorthand for docker.io/library/nginx).
  • The repository is the name of the image; the tag selects a version. If you leave the tag out, Docker uses latest.
  • The digest pins one exact manifest.

Tags are labels that move

A tag is just a pointer from a human-friendly name to a digest, and the owner of the repository can repoint it at any time. alpine:latest today is a different image from alpine:latest last year; python:3.13 changes whenever a security patch is released. Our own tags demonstrate the pointer idea: tcd-img:latest and tcd-img:2 were created with docker tag and refer to the same ID. One image can have many tags, and a tag can be moved by tagging another image with the same name.

Digests are fixed

A digest is the hash of a manifest, and it cannot move. List digests with --digests:

CONSOLE
$ docker image ls --digests alpine
REPOSITORY   TAG       DIGEST                                                                    IMAGE ID       CREATED        SIZE
alpine       latest    sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a   be2656061b53   40 hours ago   13MB
alpine       3.22      sha256:2e0b81d60597f449baa56dc25d355367869d2dca4cd57e866f1e2b52af3eb55f   2e0b81d60597   42 hours ago   12.9MB

Reference an image by digest with @, and you will get exactly those bytes, whatever happens to the tag:

CONSOLE
$ docker run --rm alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a cat /etc/alpine-release
3.24.3

Use tags for convenience while developing. For builds that must be reproducible, and for security-sensitive production deployments, pin the digest (Image Security and Tagging Strategies discuss this).

latest is not "the newest version" by any rule of Docker. It is simply the default tag name, and it points at whatever its publisher last tagged that way (or at nothing recent at all). Never deploy :latest to production: a restart on another day can silently give you a different image.

One tag, many platforms

Notice that the first digest above (be2656061b53...) differs from the one inside the manifest we printed earlier (c26612752c78...). The tag alpine:latest points to a manifest index (also called a manifest list) that lists one manifest per CPU architecture:

CONSOLE
$ docker buildx imagetools inspect alpine
Name:      docker.io/library/alpine:latest
MediaType: application/vnd.oci.image.index.v1+json
Digest:    sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a

Manifests:
  Name:        docker.io/library/alpine:latest@sha256:c26612752c78...
  MediaType:   application/vnd.oci.image.manifest.v1+json
  Platform:    linux/amd64
  ...

When you pull, Docker picks the entry that matches your machine (linux/amd64 on a typical PC, linux/arm64 on an Apple Silicon Mac) and downloads only that. This is how one name works everywhere. Multi-Platform Images covers building such images yourself.

Official images and where images come from

Images come from three places:

  1. Docker Official Images: a curated set of repositories in the library namespace, such as alpine, nginx, postgres, python, node, redis and mysql. They are maintained with security updates, follow documented conventions and have clear tags. When you need a database or a language runtime, start here.
  2. Verified publishers and sponsored open source: images from vendors (for example a database company) or open-source projects, marked with a badge on Docker Hub.
  3. Everything else: any user or organization can publish. Treat these like any third-party download: check the source, the update history and the number of pulls, and prefer images that publish their Dockerfile and are rebuilt regularly.

An image you pull will run code on your machine with the power of a container, so the usual rule applies: do not run what you do not trust. Registries and your own repositories are the subject of Tags and Registries.

Building your own: the next step

You create images with a Dockerfile and docker build; each instruction that changes the filesystem becomes a layer, as our two-line example showed (RUN echo "two" > /two.txt added the 8.19 kB layer you saw in docker history):

CONSOLE
$ docker history tcd-img:2
IMAGE          CREATED         CREATED BY                                      SIZE      COMMENT
5c3016ebc8d7   7 seconds ago   CMD ["cat" "/one.txt" "/two.txt"]               0B        buildkit.dockerfile.v0
<missing>      7 seconds ago   RUN /bin/sh -c echo "two" > /two.txt # buildโ€ฆ   8.19kB    buildkit.dockerfile.v0
<missing>      9 seconds ago   RUN /bin/sh -c echo "one" > /one.txt # buildโ€ฆ   8.19kB    buildkit.dockerfile.v0
<missing>      40 hours ago    CMD ["/bin/sh"]                                 0B        buildkit.dockerfile.v0
<missing>      40 hours ago    ADD alpine-minirootfs-3.24.3-x86_64.tar.gz /โ€ฆ   9.08MB    buildkit.dockerfile.v0

Read it from the bottom up: the base image's two entries first, then our two RUN steps, then the new CMD. Writing Dockerfiles starts in Writing a Dockerfile.

Common misconceptions

  • "An image is a snapshot of a running container." Normally not. Images are built from instructions. (docker commit can snapshot a container, but it is rarely a good idea; see Save, Load, Export, Import.)
  • "Deleting a tag deletes the image." docker rmi name:tag only removes that name. The layers disappear when no tag and no container refers to them any more.
  • "Layers are copies of the whole filesystem." Each layer only contains the difference from the layer below it.
  • "Images are small because they contain no OS." They contain the userland of an OS (libraries, tools), but not a kernel. The kernel is shared with the host, which is why containers start in milliseconds.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does a Docker image contain?

    An image is a stack of read-only layers with a JSON config and a manifest. It has no kernel; containers use the host's kernel.
  2. 2. Two images share the same first layer. What happens on disk and during a pull?

    Content-addressable storage means identical content has an identical hash, so Docker reuses the layer it already has.
  3. 3. Why is 'docker pull myapp:latest' risky for production deployments?

    Tags are movable pointers. To get exactly the same bytes every time, reference the image by its digest (name@sha256:...) or use immutable version tags.
  4. 4. How do you run exactly the image whose manifest digest is sha256:be26..., regardless of what tags currently point to?

    A digest follows the repository name after an @ sign. The result is the same bytes every time.
  5. 5. In 'docker history', the lines for older layers show <missing> in the IMAGE column. What does that mean?

    <missing> only means that this build step is not available as a separate image ID locally. The layer's content is still part of the image.

Summary

  • An image is a read-only stack of layers plus a config (command, environment, ports, user) and a manifest listing them; the format follows the OCI specification.
  • Layers, configs and manifests are identified by the SHA-256 hash of their content, which gives integrity checks and automatic sharing of identical layers.
  • Containers add a thin writable layer on top of an image and share its read-only layers; the image itself never changes.
  • A reference is registry/namespace/repository:tag@digest; the registry defaults to Docker Hub and the tag to latest.
  • Tags are movable labels. Digests are permanent. Pin digests when you need reproducibility.
  • A tag usually points to a manifest index with one entry per platform, and Docker pulls the entry for your machine.
  • Official images are curated and a good default; treat other images like any third-party download.
  • docker history, docker image inspect and docker images --digests reveal how an image is built.

Next: Pulling and Managing Images