Docker: no space left on device

The exact error string

# during a pull:
write /var/lib/docker/tmp/...: no space left on device

# during a build:
failed to solve: write /var/lib/docker/...: no space left on device

# from inside a container writing a file:
Error: ENOSPC: no space left on device, write

Docker stores everything it manages under one directory — /var/lib/docker on Linux, or a fixed-size virtual disk inside the VM on Docker Desktop. That space accumulates quietly: every image you pull, every container you stop but don't remove, every volume, and every layer of build cache stays on disk until something removes it. Eventually a pull or build needs room that isn't there, and you get no space left on device — the disk counterpart to running out of memory, which surfaces as exit code 137 (OOMKilled). The fix is to see where the space went, then reclaim the parts you don't need.

Where Docker's disk actually goes

Step 1: see where the space went

$ docker system df
TYPE            TOTAL   ACTIVE   SIZE      RECLAIMABLE
Images          42      6        18.3GB    14.1GB (77%)
Containers      15      3        1.2GB     0.9GB (75%)
Local Volumes   9       4        6.4GB     3.1GB (48%)
Build Cache     210     0        11.8GB    11.8GB (100%)

The RECLAIMABLE column is the one to read — it shows how much of each category can be freed. Here the build cache (11.8GB, 100% reclaimable) and old images (14.1GB) are the big wins, and no volume data needs touching. Add -v to docker system df -v for a per-image and per-volume breakdown.

Before you prune anything, list the individual items so you can see exactly what's about to go — especially useful for images and volumes, where a wrong assumption is expensive:

docker image ls     # every image, its tag, and size — review before pruning
docker volume ls    # every volume — check nothing here holds data you need
docker ps -a        # all containers, including stopped ones

Step 2: reclaim safely, escalating as needed

# 1) safe: stopped containers, dangling images, unused networks, build cache
docker system prune

# 2) also remove ALL unused images (not just dangling ones)
docker system prune -a

# 3) target just the build cache — often the biggest, and always safe
docker builder prune       # removes unused (dangling) cache
docker builder prune -a    # removes ALL cache no longer needed by a build

# 4) remove only dangling images
docker image prune

Work down this list rather than jumping to the most aggressive option. The plain docker system prune is safe for your data and frees stopped containers plus dangling images plus the entire build cache — frequently enough on its own. Escalate to -a when old image versions dominate. Note the difference on the cache: docker builder prune clears only dangling cache, while docker builder prune -a also removes cache that's still referenced by previous builds but no longer needed — the bigger reclaim, and safe either way since build cache is never your data.

BuildKit: the cache that quietly eats the most

Modern Docker builds use BuildKit (the default since Docker 23), which maintains its own layer cache separate from image layers. On an active development machine — where you rebuild the same project dozens of times a day — this cache is frequently the single largest consumer of disk space, and it's the one most people forget exists because it never shows up in docker image ls. It's the Build Cache line in docker system df, and docker builder prune -a is what clears it completely. If your system df shows a surprisingly large, 100%-reclaimable Build Cache (as in the example above), that's your fastest win and there's zero risk in clearing it.

The dangerous flag: --volumes

Special cases worth knowing

• Docker Desktop shows the host as free. Docker runs in a fixed-size VM, so your Mac/Windows drive can have plenty of room while the VM is full. Prune inside Docker, or raise the VM's disk-image size in Settings → Resources.
• Out of inodes, not bytes. On Linux, run df -i. Millions of tiny layer files can exhaust the inode table even with free bytes — the error is identical, and pruning images/containers frees inodes too.
• A single log file ate the disk. A chatty container with the default json-file log driver and no size cap can grow a multi-gigabyte log. Cap it in daemon.json with log-opts max-size and max-file.

Step 3: keep it from filling up again

# cron/CI: reclaim without a confirmation prompt
docker system prune -f
docker builder prune -f --filter "until=168h"   # cache older than 7 days

# cap container log growth in /etc/docker/daemon.json
{
  "log-driver": "json-file",
  "log-opts": { "max-size": "10m", "max-file": "3" }
}

Combine scheduled prunes with smaller images — multi-stage builds and -slim/-alpine base images cut image size at the source, which is the most durable way to avoid the problem returning.

Debugging checklist

• ✓ docker system df — read the RECLAIMABLE column to see the big consumers
• ✓ Start safe: docker system prune (data-safe without --volumes)
• ✓ Old image versions dominating? Add -a
• ✓ Build cache is the biggest? docker builder prune
• ✓ Never add --volumes without checking docker volume ls first
• ✓ Docker Desktop? The VM disk may be full while the host is free
• ✓ Linux with free bytes but still failing? Check df -i for inode exhaustion