Container images — layers, tags, registries and digests

An image is the template Docker creates containers from. It holds the container's files — the program, libraries, configs — and its run settings: command, environment variables, working directory, port. An image never changes. A container writes to its own layer on top of the image, so one image can back any number of containers.

The lab machine has no outside network. Images sit as files in /opt/images, and docker load brings them into Docker. Here student is not in the docker group, so every command goes through sudo.

student@ubuntu:~$ sudo docker load -i /opt/images/alpine.tar
Loaded image: alpine:latest
student@ubuntu:~$ sudo docker images
IMAGE            ID             DISK USAGE   CONTENT SIZE   EXTRA
alpine:latest    d1e016453729       17.8MB         8.71MB
busybox:latest   27be924c62a0       9.26MB         4.68MB   U
nginx:alpine     1acb5b0222ee        144MB         70.4MB

After the table docker images prints a warning, This output is designed for human readability: the table layout may change between Docker versions. Scripts need --format — see the recipe below.

Image name and registry

A registry is a server that stores images: Docker Hub, GitLab Registry, a company registry. docker pull downloads an image from it, docker push uploads one. The full image name says where it lives:

registry.example.com:5000/team/app:1.4
└── registry ───────────┘└ path ─┘└ tag

With no registry in the name Docker goes to Docker Hub; with no tag it takes latest. nginx:alpine means docker.io/library/nginx:alpine. The full name shows up in the error when the image is missing: failed to resolve reference "docker.io/library/nginx:alpine".

Layers

An image is built from layers. A layer is an archive of file changes: what was added, changed or deleted relative to the layers below. Every dockerfile instruction that changes files produces a layer. docker history lists them, newest first:

student@ubuntu:~$ sudo docker history nginx:alpine
IMAGE          CREATED      CREATED BY                         SIZE
1acb5b0222ee   5 days ago   RUN /bin/sh -c set -x && apkArch…  52.4MB
<missing>      5 days ago   CMD ["nginx" "-g" "daemon off;"]   0B
<missing>      5 days ago   EXPOSE map[80/tcp:{}]              0B
<missing>      5 days ago   COPY docker-entrypoint.sh / # bu…  8.19kB
…
<missing>      4 weeks ago  ADD alpine-minirootfs-3.24.2-x86…  9.08MB

The bottom row is the Alpine layer: nginx:alpine is built on top of the Alpine image. Rows of size 0B (CMD, EXPOSE, ENV) change no files — they record run settings. <missing> in the IMAGE column means the step has no separate image on this machine; every pulled or loaded image looks like this.

Identical layers are stored once. Ten images based on Alpine keep a single copy of its layer on disk.

Container layer

Image layers are read-only. A container gets its own writable layer on top — the container layer. A file changed inside the container is copied up into that layer (copy-on-write); the image stays as it was.

The container layer lives as long as the container: docker stop and docker start keep it, docker rm deletes it with all its data. Data that must survive re-creating a container goes into a volume — see Volumes in the Docker article.

Tag

A tag is a movable name: the part after the colon. docker tag gives the same image a second name; both names share one ID:

student@ubuntu:~$ sudo docker tag busybox:latest app:1.0
student@ubuntu:~$ sudo docker images
IMAGE            ID             DISK USAGE   CONTENT SIZE   EXTRA
app:1.0          27be924c62a0       9.26MB         4.68MB   U
busybox:latest   27be924c62a0       9.26MB         4.68MB   U

latest is just the default tag. It is used when no tag is given and says nothing about freshness: alpine:latest on this machine is whatever image was loaded into it.

A tag moves on rebuild. A second docker build -t app:1.1 hands the name to the new image, and the old one is left nameless, <none>:<none> — a dangling image. Plain docker images hides it; a filter finds it:

student@ubuntu:~$ sudo docker images --filter dangling=true \
    --format '{{.ID}} {{.Repository}}:{{.Tag}}'
a4eab66e5237 <none>:<none>

docker images -a lists such images as <untagged>.

docker rmi <name> removes a tag. If the image has other names, it stays: Untagged: busybox:latest. For the last name docker rmi deletes the image too — as long as no container needs it.

Digest and ID

A digest is the SHA-256 of the image manifest, the description of its layers and settings. Change a single byte in any layer and the digest changes. So nginx@sha256:1acb… always means the same content, while nginx:alpine may point to a different image tomorrow.

student@ubuntu:~$ sudo docker image ls --digests
REPOSITORY   TAG      DIGEST            IMAGE ID       …   SIZE
nginx        alpine   sha256:1acb5b0…   1acb5b0222ee   …   144MB
busybox      latest   sha256:27be924…   27be924c62a0   …   9.26MB

In Docker 29 images are stored by containerd, and a loaded image's ID is the same as its digest.

docker load and docker save

docker save writes an image with all its layers to a tar archive; docker load reads it back — on this machine or another one. That is how an image reaches a host with no registry access. The archive uses the OCI layout: index.json, manifest.json and a blobs/sha256 directory where every file is named after its own SHA-256.

• docker — running containers, volumes, networks, inspect.
• dockerfile — building your own image and where layers come from.
• docker-compose — several containers from one file.
• cgroups-namespaces — how a container is isolated from the host.
• tar — the docker save archive format.
• disk-usage — where the disk space went.