Skip to content
Tutorials Center
My learning

Topics

Lesson 39 of 111 ยท Containers in Depth

Cleaning Up

Reclaim disk space safely: docker system df, container, image, volume, network and build-cache prune, label and age filters, log rotation and automation.

Docker is generous with disk space and stingy about giving it back. Every docker run without --rm leaves a stopped container behind, every rebuild can orphan an old image, every docker pull of a moving tag strands the previous version, and the BuildKit cache quietly grows into tens of gigabytes. Sooner or later a laptop or a CI server reports "no space left on device", and the usual reaction is to type docker system prune -a and hope for the best.

That command works, and it can also delete things you wanted. In this lesson you will learn where the space goes, what each prune command removes (and what it deliberately leaves alone), how to restrict a cleanup with filters so that it only touches what you intend, how to stop logs from filling the disk, and how to automate regular cleanup on a build server. Everything below was run on a machine that also hosts other people's containers, so every prune is restricted by a label filter. That is not only a teaching device; it is exactly the discipline you want on a shared machine.

Where does the space go?

docker system df summarizes usage by category. The numbers below are illustrative, because yours will differ; the column names and the meaning of each row are what matter:

CONSOLE
$ docker system df
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          12        4         3.2GB     1.9GB (59%)
Containers      9         2         140MB     120MB (85%)
Local Volumes   6         2         1.4GB     900MB (64%)
Build Cache     80        0         5.1GB     5.1GB
  • Images: every image in the local store. Active images are used by at least one container.
  • Containers: the writable layers of containers, running or stopped. A stopped container still holds its files and its logs.
  • Local Volumes: data in named and anonymous volumes. Active means a container (running or stopped) references it.
  • Build Cache: layers and intermediate results kept by BuildKit so that the next build is fast.

docker system df -v expands each category into one line per object, which is how you find the particular 4 GB image or 2 GB volume behind a big number. To script it, use a format template:

CONSOLE
$ docker system df --format 'table {{.Type}}\t{{.TotalCount}}\t{{.Active}}\t{{.Size}}\t{{.Reclaimable}}'
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          60        12        15.3GB    1.996GB (13%)
Containers      13        7         6.148GB   1.946MB (0%)
Local Volumes   17        11        1.4GB     354.4MB (25%)
Build Cache     473       4         22.24GB   21.29GB

That second listing came from the test machine for this lesson, a busy shared development box: note how the build cache dominates. On developer machines it is very often the build cache, not images, that eats the disk.

Reclaimable is an estimate of what pruning could free, and it does not tell you whether you still want those objects. A volume with a database in it may count as reclaimable simply because the container that used it is stopped.

The prune family

Docker has one prune command per kind of object, plus an umbrella that runs several at once.

Command Removes Leaves alone
docker container prune All stopped containers Running and paused containers
docker image prune Dangling images (no tag, not used) Tagged images, images used by containers
docker image prune -a All images not used by any container Images used by at least one container, even a stopped one
docker volume prune Anonymous volumes not used by any container Named volumes (unless you add -a)
docker network prune Networks with no containers attached Default networks (bridge, host, none)
docker builder prune Build cache Cache a build is using right now
docker system prune Stopped containers, unused networks, dangling images, build cache Volumes (unless --volumes) and tagged images (unless -a)

Each of them asks for confirmation and accepts -f to skip the question. All of them accept --filter. We will look at the four object types in turn, using disposable objects labelled demo=1 so that nothing else on the machine is touched.

Never run a bare prune on a machine you share or on a server you do not fully understand. docker system prune -a --volumes removes every image not used by a container and every volume not used by one, including the database volume of a service you stopped for a minute. There is no undo. Prefer the specific commands with filters, and read the list that Docker prints before confirming.

Stopped containers

Containers that have exited remain until removed. Four short jobs and one long-running container:

CONSOLE
$ docker ps -a --filter label=demo --format 'table {{.Names}}\t{{.Status}}'
NAMES         STATUS
demo-live   Up 1 second
demo-job3   Exited (0) 2 seconds ago
demo-job2   Exited (0) 4 seconds ago
demo-job1   Exited (0) 5 seconds ago

docker container prune removes every stopped container. With a filter it only removes yours:

CONSOLE
$ docker container prune --filter label=demo -f
Deleted Containers:
3510230c63ad...
a72ae5bf0d3d...
99f6b214b9d2...

Total reclaimed space: 12.29kB
$ docker ps -a --filter label=demo --format 'table {{.Names}}\t{{.Status}}'
NAMES         STATUS
demo-live   Up 46 seconds

(IDs shortened.) The running container survived. Filters you can use: label=..., label!=... and until=24h (containers created more than 24 hours ago). Together --filter until=72h is a good default for "stopped and forgotten".

Better than cleaning up is not leaving containers behind. For one-off commands add --rm, which removes the container, with its logs and its writable layer, when it exits (do not use it while you are still debugging a failure; see Debugging Containers). The rest you can remove by name or by filter without a prune:

Terminal
docker rm demo-job1 demo-job2
docker ps -aq --filter status=exited --filter label=demo | xargs -r docker rm

Images and dangling images

An image becomes dangling when it has no tag and nothing uses it. It happens when a tag moves to a newer image (a rebuild, or a docker pull that finds a new version) and the previous image loses its name. The dangling image still occupies disk space, so we can list and remove it by itself. Here one was created from a container with docker commit:

CONSOLE
$ docker image ls --filter dangling=true --filter label=demo
IMAGE        ID             DISK USAGE   CONTENT SIZE   EXTRA
<untagged>   aa39b2385420       12.8MB          3.8MB
$ docker image prune --filter label=demo -f
Deleted Images:
untagged: sha256:aa39b23854208ddc2aa2dc0de621529f3d28b43700f98dbc3814b6ecfafad49e
deleted: sha256:aa39b23854208ddc2aa2dc0de621529f3d28b43700f98dbc3814b6ecfafad49e

Total reclaimed space: 1.308kB

The filter label=demo matches labels baked into the image with LABEL demo=1 in the Dockerfile (or docker commit --change 'LABEL demo=1'). That is a great habit for CI: label every image your pipeline builds (LABEL ci=true) so that a cleanup job can target exactly those.

docker image prune -a goes further: it removes every image that no container references, tagged or not. That includes the base images you pulled last week and will download again on the next build, and images for containers you removed. On a build server this is normal and fine; on a laptop it just trades disk space for download time.

CONSOLE
$ docker image prune -a --filter label=demo
WARNING! This will remove all images without at least one container associated to them.
Are you sure you want to continue? [y/N]

(We answered n.) Prefer age filters over wiping everything: docker image prune -a --filter "until=168h" removes unused images created more than a week ago, which keeps recent ones warm.

To remove one specific image (and untag it) use docker rmi NAME; see Pulling and Managing Images. A tag that points at an image used by a container cannot be removed until the container is, and docker rmi -f is rarely the right answer.

Volumes: the dangerous one

Volumes hold data, so pruning them has a safety rule of its own. Since Docker Engine 23, docker volume prune removes only anonymous volumes by default, and keeps named ones. We created three named volumes; one is used by a running container:

CONSOLE
$ docker volume ls --filter label=demo --format 'table {{.Name}}\t{{.Driver}}'
VOLUME NAME     DRIVER
demo-keep     local
demo-unused   local
demo-used     local
$ docker volume ls --filter dangling=true --filter label=demo --format '{{.Name}}'
demo-keep
demo-unused
$ docker volume prune --filter label=demo
WARNING! This will remove anonymous local volumes not used by at least one container.
Are you sure you want to continue? [y/N] Total reclaimed space: 0B

(We answered n.) "Dangling" volumes are those no container references. To prune named unused volumes too, you must add -a, and you can protect some by label. Let us also create a volume labelled keep=yes:

CONSOLE
$ docker volume ls --filter label=demo --format 'table {{.Name}}\t{{.Labels}}'
VOLUME NAME     LABELS
demo-keep     demo=1
demo-keep2    keep=yes,demo=1
demo-unused   demo=1
demo-used     demo=1
$ docker volume prune -a --filter label=demo --filter label!=keep -f
Deleted Volumes:
demo-unused
demo-keep

Total reclaimed space: 0B
$ docker volume ls --filter label=demo --format '{{.Name}}'
demo-keep2
demo-used

Two volumes were removed (the name demo-keep is just a name; it had no keep label). The one carrying the label keep=yes survived, and so did the volume that a container uses. label!=keep is a handy safety net: label irreplaceable volumes (docker volume create --label keep=yes pgdata) and add the negative filter to every automated prune. See Volumes for creating and labelling them.

Anonymous volumes pile up quietly

Some images declare a VOLUME in their Dockerfile, and -v /data without a name creates an anonymous volume with a random 64-character name. docker rm leaves it behind; docker rm -v removes it together with the container:

CONSOLE
$ docker run --name anon -v /data alpine:3.22 true
$ docker inspect -f '{{range .Mounts}}{{.Type}} {{.Name}} -> {{.Destination}}{{end}}' anon
volume 6d304858c330... -> /data
$ docker rm anon
$ docker volume ls -q | grep -c 6d304858c330
1

After the plain docker rm, the volume (1 match) is still there. Repeating the experiment with docker rm -v anon leaves 0 matches. A large number of hash-named entries in docker volume ls is the sign. Name your volumes, and you will always know what they are for.

Networks

Networks cost almost no disk space, but unused ones clutter docker network ls, and each user-defined bridge consumes an address range from Docker's pool, which can run out on a host with hundreds of Compose projects.

CONSOLE
$ docker network prune --filter label=demo -f
Deleted Networks:
demo-net

The built-in networks and any network with a container attached are never removed.

The build cache

BuildKit keeps the result of every build step so that unchanged steps are skipped (see The Build Cache). The cache is invisible in docker images, which is why it surprises people. To demonstrate safely we created a separate builder so that the experiments cannot touch anyone's real cache:

CONSOLE
$ docker buildx create --name demo-builder --driver docker-container
$ docker buildx build --builder demo-builder -f Dockerfile.cache -t cachedemo --load .
$ docker buildx du --builder demo-builder
ID                           RECLAIMABLE   SIZE      LAST ACCESSED
qfkhotxiqlzuqlw484op5tuto*   true          4.096kB   1 second ago
l4vhb74i56b8e2ap7l0evckgg*   true          8.192kB   1 second ago
mp1nc0fla7izipuqu0vvj30mm*   true          8.192kB   1 second ago
w3g0psoa6j93xdpwh1x6m7upz    true          8.308kB   1 second ago
olxse7hth9ewgy1y6fr4nplzm    true          7.719MB   1 second ago
wquqmdqy4ikt9yangwselj4ho    true          10.5MB    1 second ago
0gub72nthl69kfe5hpxxluyau    true          12.76MB   1 second ago
Reclaimable:	31.01MB
Total:		31.01MB

docker buildx du lists cache records (the ones with * are shared by several records). Pruning supports the same --filter until= age filter. A prune of records older than a day found nothing to remove, because everything was brand new, and then -a cleared the rest:

CONSOLE
$ docker buildx prune --builder demo-builder --filter until=24h -f
Total:	0B
$ docker buildx prune --builder demo-builder -a -f
ID						RECLAIMABLE	SIZE		LAST ACCESSED
0gub72nthl69kfe5hpxxluyau               	true 		12.76MB   	9 seconds ago
Total:	12.76MB
$ docker buildx du --builder demo-builder
ID        RECLAIMABLE   SIZE      LAST ACCESSED
Reclaimable:	0B
Total:		0B

(The command printed more records than shown; we kept the last.) For your normal builder the command is docker builder prune, which is the same as docker buildx prune for the current builder. Useful variations: docker builder prune --filter until=168h (keep the last week), docker builder prune -a (also internal frontend images) and the size limits --max-used-space 10GB or --reserved-space that keep the cache bounded instead of emptying it. The cost of clearing it is slower builds afterwards, so on laptops prefer a size or age limit over a full wipe. When you are finished with a separate builder, remove it with docker buildx rm demo-builder.

What docker system prune does

docker system prune is the combination you will see in tutorials: stopped containers, unused networks, dangling images and (in current versions) build cache. Flags change its reach:

Flag Extra effect
-a Also removes all unused images, not just dangling ones
--volumes Also removes anonymous volumes (with -a as well, unused named volumes)
--filter until=24h Only objects older than the given age
--filter label=... Only objects with the label (or without, with !=)
-f No confirmation prompt

We deliberately did not run it here because on this machine it would delete other people's work. Treat it as a read-only example:

CONSOLE
$ docker system prune --filter "until=168h" --filter label!=keep    # read-only example

Docker prints exactly what it is about to do and asks for confirmation; read that list.

Compose and orphans

Compose has its own cleanup switches, and most leftover volumes in practice come from forgetting them. docker compose down removes the containers and the default network but keeps volumes. Add --volumes to delete the project's named volumes and --remove-orphans to remove containers of services that are no longer in the file. Here a project with two services was started, then restarted with a file that dropped one of them:

CONSOLE
$ docker compose -f compose2.yaml up -d
time="..." level=warning msg="Found orphan containers (demo-extra-1) for this project. If you removed or renamed this service in your compose file, you can run this command with the --remove-orphans flag to clean it up."
 Container demo-app-1 Running
$ docker compose -f compose2.yaml down
 Container demo-app-1 Stopping
 Container demo-app-1 Stopped
 Container demo-app-1 Removing
 Container demo-app-1 Removed
 Network demo_default Removing
 Network demo_default Resource is still in use
$ docker volume ls --filter name=demo --format '{{.Name}}'
demo_data
$ docker compose -f compose2.yaml down --volumes --remove-orphans
 Container demo-extra-1 Stopping
 Container demo-extra-1 Stopped
 Container demo-extra-1 Removing
 Container demo-extra-1 Removed
 Network demo_default Removing
 Volume demo_data Removing
 Volume demo_data Removed
 Network demo_default Removed

The orphan container (still attached to the network) kept the network from being removed, and the plain down kept the volume. The second down with both flags cleaned up everything. --rmi local also removes images built by the project. See Compose Commands.

Logs can fill the disk too

By default Docker stores each container's output in a JSON file on the host and never rotates it. A chatty service can fill the disk even if images and volumes are tiny. Rotate with the json-file driver's options, per container or in the daemon configuration:

CONSOLE
$ docker run -d --name chatty --log-opt max-size=100k --log-opt max-file=2 alpine:3.22 sh -c 'i=0; while [ $i -lt 6000 ]; do echo "line $i: some noisy log output that fills the log file quickly"; i=$((i+1)); done; sleep 30'
$ docker inspect -f '{{.HostConfig.LogConfig.Type}} {{json .HostConfig.LogConfig.Config}}' chatty
json-file {"max-file":"2","max-size":"100k"}
$ docker logs chatty | wc -l
798
$ docker logs chatty | tail -1
line 5999: some noisy log output that fills the log file quickly

The program wrote 6000 lines but only 798 remain: the logging driver keeps at most two files of 100 KB each and drops the oldest. Real services use bigger limits (max-size=10m, max-file=3), set once for the whole host in /etc/docker/daemon.json:

JSON
{
  "log-driver": "json-file",
  "log-opts": { "max-size": "10m", "max-file": "3" }
}

In Compose, put logging: { driver: json-file, options: { max-size: "10m", max-file: "3" } } on a service. More options are in Logging and Monitoring. The default limits apply to containers created after the change, so recreate existing ones.

Automating cleanup

On a CI runner or a long-lived server, schedule a modest, age-based cleanup rather than a nightly wipe. A weekly job might look like this (a read-only example; adapt the ages to your policy):

Terminal
#!/bin/sh
# /etc/cron.weekly/docker-cleanup
set -eu
docker container prune -f --filter "until=168h"
docker image prune -a -f --filter "until=720h" --filter "label!=keep"
docker builder prune -f --filter "until=336h"
docker network prune -f --filter "until=168h"
# volumes are never pruned automatically

Design rules that keep automation safe:

  1. Use age, not "everything". Recent objects are likely in use or about to be.
  2. Label what must survive (keep=yes) and always add label!=keep.
  3. Do not auto-prune volumes. Data loss is permanent. List candidates (docker volume ls -f dangling=true) and review them by hand or by a separate, explicit process.
  4. Cap, don't wipe, the build cache so CI stays fast.
  5. Log what was removed; the output of the prune commands is your audit trail.
  6. Rotate logs at the daemon level so a runaway service cannot fill the disk between cleanups.

Finally, measure again. After the job runs, docker system df should show the reclaimable column near zero; if it keeps growing, find the source (usually builds without a cache limit or containers started without --rm).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does a plain docker volume prune (without -a) remove on a current Docker Engine?

    Since Docker Engine 23 the default only deletes anonymous unused volumes, as a protection for named data. Add -a to include unused named volumes, and use --filter label!=keep to protect specific ones.
  2. 2. How does Docker decide that an image is "dangling"?

    A dangling image has lost its name, typically because a rebuild or pull moved the tag to a newer image. docker image prune removes these; -a also removes tagged images that no container uses.
  3. 3. Why is docker system prune -a --volumes risky on a shared server?

    'Unused' means 'no container references it right now'. A stopped service's database volume qualifies, as do images other teams will need. Use specific prunes with age and label filters instead.
  4. 4. A project's docker compose down finished, but its named volume and a container of a removed service are still there. Which command cleans up both?

    down keeps volumes by default and leaves containers of services that are no longer in the file (orphans). --volumes deletes the named volumes, --remove-orphans removes the orphan containers.
  5. 5. How do you keep a container's log files from growing without limit?

    The json-file driver never rotates by default. max-size and max-file cap the files, and the oldest lines are dropped (798 of 6000 lines remained in our demonstration).

Summary

  • docker system df (and -v) shows where the space went; on developer machines the build cache is often the largest part.
  • There is one prune per object type; each accepts -f and --filter. Filters (label=, label!=, until=) make a cleanup precise.
  • container prune removes stopped containers, image prune dangling images (-a for all unused ones), network prune unused networks, builder prune the build cache.
  • volume prune only removes anonymous volumes by default; -a includes unused named volumes. Label irreplaceable volumes keep=yes and add label!=keep.
  • docker rm -v removes a container's anonymous volumes; docker compose down --volumes --remove-orphans cleans a whole project.
  • Rotate logs with max-size and max-file; avoid leftover containers with --rm.
  • Automate with age-based pruning, never auto-prune volumes, and avoid bare docker system prune -a --volumes on shared machines.

Next: Container Storage