I ran docker system df before I deleted anything. The error was no space left on device, it showed up in the middle of a build, and the instinct is to start pruning everything in sight. That instinct is how people lose database files. So I looked first.
Docker never throws things away on its own initiative. Old image layers, build cache, stopped containers and unused tags pile up until the disk is full, and then a build or container start falls over. Getting space back is easy. Getting it back without touching your data takes a little care.
Look before you delete #
Start with how full the disk actually is, then with what Docker thinks it’s using:
df -h /var/lib/docker
df -i /var/lib/docker
docker system dfThe df -h line tells you whether the partition is really full, and df -i checks inodes, because a disk with plenty of free bytes can still refuse to create files when it runs out of them. docker system df splits usage into images, containers, local volumes and build cache, with a reclaimable column next to each. That column is your map. If build cache and images dominate, you can clear space without going near a volume. If volumes dominate, pruning won’t save you, and you have a different problem.
Where the data lives matters too. On Linux, Docker keeps everything under /var/lib/docker. But since Docker Engine 29, fresh installations use the containerd image store by default, which keeps image contents and container snapshots in /var/lib/containerd, and leaves volumes and configs in /var/lib/docker. Upgraded installs keep the classic drivers like overlay2. To see which one you’re on:
docker info -f '{{ .DriverStatus }}'If the output mentions io.containerd.snapshotter.v1, you’re on the containerd store and your image data isn’t under overlay2 at all. One more detail from Docker’s docs: containerd keeps the compressed layers as pulled and also extracts them to disk, so each layer takes up more room.
And one rule, whichever driver you have. Don’t delete anything inside /var/lib/docker/overlay2 by hand. The daemon tracks those directories by ID, and removing them behind its back leaves images and containers that point at nothing. Let Docker do the deleting. On Docker Desktop for Mac or Windows, the data lives inside the VM rather than on your host path, so docker system df is the number to trust.
Build cache first, because it’s the safest #
Build cache is the one category that’s purely a convenience. Delete it and your next build runs slower while it rebuilds. Nothing breaks. Start there:
docker builder pruneThat removes dangling cache only. To clear all unused cache, add -a. If you’d rather keep recent work, add an age filter, for example --filter until=72h. Two things to know before you run it. Dropping the cache also drops cache mounts from RUN --mount=type=cache steps, so package-manager downloads inside builds start cold again. And if you’ve created extra builders with buildx, remember that docker buildx prune only clears the cache of the currently selected builder, and each builder keeps its own. Pass --builder to target another one.
I leave -f off these commands on purpose. Without it, Docker prints what it’s about to remove and waits for a yes. That prompt is the only safety net in this whole process, so keep it.
Stopped containers #
Stopped containers hold on to a writable layer. Everything a container wrote outside a volume lives there, and it dies with the container. That’s the trade you’re making with docker container prune. Look at what’s about to go first:
docker ps -a --filter status=exited
docker container pruneIf a service stack is stopped on purpose, its containers get recreated the next time you bring it up. If a container holds state you haven’t put in a volume, that state is gone after the prune.
Images #
Old tags pile up every time you rebuild or pull a new version. docker image prune removes dangling images, the untagged <none> leftovers from builds. To remove everything unused, add -a.
Here “unused” means something specific. An image counts as unused when no container is associated with it, and that includes stopped containers, not just running ones. So order matters. Prune stopped containers first and the images they pointed at become eligible for image prune -a. Run the commands in the other order and those images survive. Base images like node or alpine will be pulled again on your next build, which costs some bandwidth and nothing else. Add --filter "until=24h" if you want to keep anything recent.
The one-command version #
When you want all of it at once, docker system prune -a covers the lot. According to Docker’s docs it removes stopped containers, networks not used by any container, all images without an associated container, and all build cache. It leaves volumes alone: volumes aren’t removed by default, so data isn’t deleted just because no container is using the volume at that moment. The same --filter "until=24h" works here if you want a gentler pass.
About --volumes
#
The flag you don’t want to type by reflex is --volumes, and the full story is more specific than most guides make it sound. On current Docker, since API version 1.42, system prune --volumes and volume prune only remove anonymous volumes unless you explicitly ask for named ones too. To include named volumes you need docker volume prune --all. So named volumes are safer than they used to be. Anonymous volumes aren’t safe, though, because plenty of people have real data in one without knowing it.
Here’s how. If you start a database container without naming a volume, Docker still creates one, with a random name, to hold the data directory. As long as the container exists, that volume is in use. Prune the stopped container and the volume becomes unused. Then --volumes deletes it. The data you thought was safe vanishes with one flag.
Before pruning anything that touches volumes, list what’s loose:
docker volume ls
docker volume ls -f dangling=trueAnything dangling that looks like it holds real data, back it up or give it a proper name first.
Check that it worked #
Run the first commands again:
docker system df
df -h /var/lib/dockerIf the numbers barely moved, the space isn’t in images or cache. Look at what’s running. Running containers keep their writable layers, and container logs can grow without limit under the default json-file driver, so check sudo du -sh /var/lib/docker/containers. If logs are the culprit, set max-size and max-file under log-opts in your daemon config to cap them.
Keep it from happening again #
Docker’s build garbage collection runs on its own, and Docker’s docs say the default behavior is enough for most users. On a small VPS disk, though, a default that’s sized as a share of a big disk can still be too generous, so it’s worth setting an explicit cap. For the default builder, that goes in /etc/docker/daemon.json:
{
"builder": {
"gc": {
"enabled": true,
"defaultKeepStorage": "5GB"
}
}
}That file only configures GC for builders that use the docker driver; other drivers use a separate BuildKit config file. If daemon.json already exists, merge these keys into it instead of replacing it, because a malformed file will stop the daemon from starting.
Then comes the restart, and this is where you can take your own services down. By default, when the Docker daemon terminates, it shuts down running containers. sudo systemctl restart docker does exactly that. If you can’t afford the downtime, enable live restore first by adding "live-restore": true to the same file. On Linux you can apply that setting with systemctl reload docker and avoid downtime. Once it’s on, restarting the daemon leaves your containers running.
sudo systemctl restart dockerDocker is built to keep anything you might want again, and that includes the layer you stopped using in March. Reclaiming space means deciding what you won’t want again. Docker can’t make that call for you, and now you know which commands are safe to run before you make it.