Housekeeping: disk usage and cleanup

Docker will fill your disk

Everything in this course so far accumulates: every build leaves layers behind, every stopped container keeps its writable layer, every pulled image stays until deleted, and the build cache grows without limit. On a working developer's machine this quietly reaches tens of gigabytes, and "no space left on device" breaking builds is one of the most common Docker problems on dev laptops and CI machines (CI is short for continuous integration: the automated machines that build and test every push) alike.

The overview command:

docker system df

TYPE            TOTAL   ACTIVE  SIZE     RECLAIMABLE
Images          24      3       11.2GB   9.8GB (87%)
Containers      11      2       420MB    390MB (92%)
Local Volumes   8       2       2.1GB    1.4GB (66%)
Build Cache     142     0       6.3GB    6.3GB

RECLAIMABLE is space used by things nothing currently references: stopped containers, unused volumes, dangling images (a term worth defining: image layers left with no tag, created when you rebuild myapp:v1 and the tag moves to the new build, orphaning the old one).

A recorded session

This recorded session walks the cleanup routine: check usage, prune, and confirm the space came back.

Step 1. Start with the overview. Note the reclaimable column.

$ docker system df
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          24        3         11.2GB    9.8GB (87%)
Containers      11        2         420MB     390MB (92%)
Local Volumes   8         2         2.1GB     1.4GB (66%)
Build Cache     142       0         6.3GB     6.3GB

Step 2. Remove everything unreferenced: stopped containers, dangling images, unused networks, and the build cache. Docker asks for confirmation first.

$ docker system prune
WARNING! This will remove:
  - all stopped containers
  - all networks not used by at least one container
  - all dangling images
  - unused build cache
Are you sure you want to continue? [y/N] y
Deleted Containers: 9
Deleted Images: 14
Total reclaimed space: 15.7GB

Step 3. Check the overview again. Volumes were NOT touched, prune leaves them alone unless you explicitly add --volumes.

$ docker system df
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          3         3         1.4GB     0B (0%)
Containers      2         2         30MB      0B (0%)
Local Volumes   8         2         2.1GB     1.4GB (66%)
Build Cache     0         0         0B        0B

docker inspect, the full truth about one object

Cleanup's sibling skill is inspection. Every Docker object, whether container, image, volume, or network, carries a full JSON description of how it is actually configured, and docker inspect prints it:

docker inspect web
docker inspect --format '{{.State.Status}}' web

The first form dumps everything about the container, including environment variables, mounts, network IPs, restart policy, and ports. The second extracts a single field, which is what scripts use.

This is the tool for figuring out what a container is actually running with: which image exactly, which env values, which volume is mounted where. When a container someone else started behaves strangely, docker logs from lesson 2-3 tells you what it said, and docker inspect tells you what it is.

What system prune removes

A confirmed docker system prune deletes stopped containers, dangling images, unused networks, and the build cache.

Prune only removes what nothing references: stopped containers, images with no tag pointing at them, networks with no attached containers, and cached build layers.

Volumes are deliberately excluded, because volumes are where irreplaceable data lives. That exclusion is the single most important thing to know about the command, since --volumes on a machine running a database can destroy real data.

The disk usage summary command

The command is docker system df.

It prints a per-category summary covering images, containers, volumes, and build cache, with how much disk each uses and how much is reclaimable.

Reading the RECLAIMABLE column tells you whether a cleanup is worth running at all. On CI machines this pair often runs on a schedule, to keep builders from filling up between jobs.