Clean Up: Images, Containers and Disk Space

See what Docker keeps on your disk, remove what you no longer need and learn which prune commands to avoid. After this, you can free disk space without deleting something you wanted.

5 min Docker Testing and Debugging Deployment and Containers Beginner

Skip ahead: If you only want the safe commands, skip to "Remove one thing at a time", then go on to the next lesson.

Docker keeps everything until you remove it: stopped containers, old images, volumes, build cache. None of it shows up in a folder you would notice, and it adds up. This lesson shows how to see where the space went and how to remove things without taking anything you still need. The order matters: look first, then remove one thing at a time, and use the broad commands last.

Look before you delete

docker system df

TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          36        16        35.2GB    20.36GB (57%)
Containers      16        4         13.04MB   8.417MB (64%)
Local Volumes   29        10        2.807GB   371.1MB (13%)
Build Cache     307       0         25.71GB   13.63GB

Four rows: images, containers, local volumes and build cache. "Reclaimable" is what could be freed. Your numbers will differ, and mine come from a development machine that has been used for a while. For volumes, the reclaimable figure counts volumes no container uses, and that may include a database you meant to keep. Treat the volume number as a question, not as a to-do.

⚠ Warning: docker system prune removes every stopped container, every unused network, every dangling image and all unused build cache, for everything on the machine and not only for your project. With -a it also removes every image no container uses, and with --volumes it removes unused volumes, including data. I did not run it for this lesson, because it would also touch things that are not part of it. Read what a prune lists before you answer yes, and prefer the narrower commands below.

Remove one thing at a time

Containers first. Start two that finish at once, so they are stopped but not removed.

docker run --name job-one alpine:3.24 echo one
docker run --name job-two alpine:3.24 echo two
docker ps -a --filter name=job- --format "table {{.Names}}\t{{.Status}}"

one
two
job-two
job-one

Remove them by name. docker rm takes several names.

docker rm job-one job-two

job-one
job-two

A narrower broom exists for many at once: docker container prune removes all stopped containers, so it can take other projects' stopped containers with it. Add a filter to limit it. Here every container carries a label that I put on it, and the filter only matches those.

docker run --label course=docker-beginners --name job-three alpine:3.24 true
docker run --label course=docker-beginners --name job-four alpine:3.24 true
docker container prune -f --filter "label=course=docker-beginners"

Deleted Containers:
Total reclaimed space:

Images are next. Build a small image, then start a container from it and let the container stop.

FROM alpine:3.24
LABEL course=docker-beginners
COPY note.txt /note.txt
CMD ["cat", "/note.txt"]

Set-Content note.txt "first build"
docker build -q -t cleanup-demo:1 .
docker run --name job-five cleanup-demo:1

sha256:b87ea3f21d78999ec8bfd343f6f60f1168f71bcecf32a82f552c4993583f1633
first build

Now try to remove the image. A stopped container still counts as a user of its image, so Docker refuses.

docker image rm cleanup-demo:1

Error response from daemon: conflict: unable to delete cleanup-demo:1 (must be forced) - container 3c392a6aebd2 is using its referenced image b87ea3f21d78

The message names the container. Remove the container first, then the image.

docker rm job-five
docker image rm cleanup-demo:1

job-five
Untagged: cleanup-demo:1

docker image rm takes a name and tag. docker image prune is the broad version for images. It removes dangling images, which are builds that lost their tag and show as <none>. How many you get depends on how the image store handles a moved tag. In my test on Docker 29.6.2, rebuilding the same tag left no <none> image behind, so there was nothing to prune. I limited the command to images carrying my label, so it could not reach anything else.

docker image prune -f --filter label=course=docker-beginners

Total reclaimed space: 0B

Add -a and prune removes every image that no container uses, not only the dangling ones. That includes images you pulled yesterday and will want tomorrow. It is a fine command on a machine where you know every image, and a bad one on a shared development machine.

Volumes and networks work the same way. docker volume rm notes-data and docker network rm app-net remove one by name. Both refuse while something is using them.

Compose, in one line

docker compose down removes a project's containers and network. Add -v to remove its named volumes and --rmi local to remove images built by the project. That is the clean way to remove a whole project, because Compose knows exactly which resources are its own.

Why Windows may not get the space back

Docker Desktop keeps its data in a virtual disk on your drive. Removing images frees space inside that disk. The file itself may not shrink straight away, so Windows may keep showing the drive as full. If the numbers in docker system df dropped and your drive did not, that is the reason, and Docker Desktop's settings are where you manage the disk.

💡 Tip: Name your own throwaway containers with a common prefix or label. Then a cleanup can name exactly what is yours, and no cleanup needs the broad commands.

If docker system df says 10 GB is reclaimable in volumes, what must you check before you remove any of it?

About