Image vs container

Words used on this page

image

A read-only template: a stack of filesystem layers plus configuration such as the default command. Building or pulling it does not run anything.

container

An instance created from an image, with its own writable layer on top of the image's layers. It exists, running or stopped, until you remove it.

layer

One set of filesystem differences, made by a Dockerfile instruction that changes files. Image layers are read-only and shared by every image and container that uses them.

writable layer

Also called the container layer: the thin layer Docker adds for each container. Every file the container creates, changes or deletes is recorded there, and it is deleted with the container.

copy-on-write

Files are read from the image's layers until a container changes one. Then the file is copied up into the writable layer first; with overlay filesystems the whole file is copied, even for a small change.

storage driver and snapshotter

The part of Docker that stacks the layers on disk: a classic storage driver such as overlay2, or a containerd snapshotter (overlayfs by default) in the containerd image store.

volume

Storage that Docker manages outside any container's layers. It keeps its data when the containers using it are removed.

virtual size

In docker ps --size, the read-only image data a container uses plus its own writable layer. Containers from one image share that image data, so adding their virtual sizes overstates disk use.

Five containers, one image, three small writes

Quoted from the copy-on-write walkthrough in Docker's Storage drivers page, not reproduced: Docker is not installed on the machine this page was checked on, and the page does not say which Engine version it used. Earlier steps built acme/my-final-image:1.0, a small Alpine-based image, and started five containers from it, my_container_1 to my_container_5, each running bash. The page shows no output for the loop, and the loop's {1..3} needs bash or zsh. The page describes classic storage drivers such as overlay2; Engine 29.0 and later use the containerd image store on fresh installs, where Docker says these examples won't reflect how your system stores images.

Command

for i in {1..3}; do docker exec my_container_$i sh -c 'printf hello > /out.txt'; done
docker ps --size --format "table {{.ID}}\t{{.Image}}\t{{.Names}}\t{{.Size}}"

Output · as shown in Docker docs: Storage drivers, copy-on-write walkthrough

$ for i in {1..3}; do docker exec my_container_$i sh -c 'printf hello > /out.txt'; done

$ docker ps --size --format "table {{.ID}}\t{{.Image}}\t{{.Names}}\t{{.Size}}"

CONTAINER ID   IMAGE                     NAMES            SIZE
cddae31c314f   acme/my-final-image:1.0   my_container_5   0B (virtual 7.75MB)
939b3bf9e7ec   acme/my-final-image:1.0   my_container_4   0B (virtual 7.75MB)
3ed3c1a10430   acme/my-final-image:1.0   my_container_3   5B (virtual 7.75MB)
a5ff32e2b551   acme/my-final-image:1.0   my_container_2   5B (virtual 7.75MB)
40ebdd763416   acme/my-final-image:1.0   my_container_1   5B (virtual 7.75MB)

How to read it

• All five rows show virtual 7.75MB: the read-only image data each container uses. It is the same image data, stored once, so five containers do not cost five copies.
• SIZE is each container's own writable layer. The three containers that wrote /out.txt show 5B, the five bytes of hello; my_container_4 and my_container_5 still show 0B.
• The write went into three separate writable layers, not into the image. Docker's page notes that this data is unique to each container and not shared, so the other two containers have no /out.txt.
• Remove my_container_1 and its writable layer goes with it, file included. The image, and the other containers' layers, stay as they were. A new container from the same image starts at 0B again.
• The disk use of a container is more than SIZE: Docker's page lists log files, volumes and bind mounts, and the container's configuration files as extra space that this column does not count.