Skip to content
Underread
Guides

How to Fix “no space left on device” in Docker (When the Disk Looks Empty)

df says you have room. Docker disagrees. They're both right, and the gap is where your disk went.

By Vemuri Abhiram6 min read
Rows of storage drives in a server chassis
Rows of storage drives in a server chassis
On this page

A build or a model pull dies part-way through:

failed to register layer: write /var/lib/docker/overlay2/...:
no space left on device

You check the disk. There's plenty free. You check again, more carefully, and there still is.

Both things are true at once, and the explanation is usually one of 2 things: Docker is measuring a different volume from the one you looked at, or it's out of inodes rather than bytes.

#Find out what's actually full

Command Tells you
docker system df What Docker is using, by category
df -h /var/lib/docker Space on the volume Docker lives on
df -i Inodes, the one people forget
docker system df -v Per-image and per-volume detail

#1. Ask Docker, not the operating system

Start here, because it immediately splits the problem:

docker system df

You get 4 rows — images, containers, local volumes and build cache — each with a total and a reclaimable figure. The reclaimable column is the one that matters. If build cache is showing tens of gigabytes, which it very often is on a machine that builds regularly, you've found your answer and section 3 is a 1-line fix.

On Mac and Windows there's an extra layer worth knowing about. Docker Desktop runs containers inside a virtual machine with its own virtual disk, and that disk has a fixed maximum set in Docker's settings. Your host can have 400 GB free while that virtual disk is completely full. That's exactly the case where df -h looks healthy and Docker fails anyway.

#2. Check inodes before you start deleting

This is the one that wastes an afternoon if you miss it. A filesystem can be out of inodes — the structures that track individual files — while plenty of bytes remain free. Container layers create enormous numbers of small files, so this is a realistic failure mode rather than a curiosity:

df -i

If IUse% is at or near 100 while df -h shows space, deleting a few large files changes nothing. You need to remove many small ones, which in practice means pruning images and build cache rather than hunting for big logs.

#3. Reclaim the safe things first

In increasing order of how much they remove, and how much you should think first:

docker builder prune          # build cache — almost always safe
docker image prune            # dangling images only
docker image prune -a         # every image not used by a container
docker container prune        # stopped containers

Build cache is nearly always the biggest, and it's the safest. Start there. It rebuilds on demand, so the only cost of clearing it is a slower next build. I'd run that first and re-check docker system df before doing anything else, because it often ends the problem on its own.

docker image prune -a is more aggressive than it sounds. It removes anything not currently used by a container, which includes images you'll want again and will have to pull. That's time and bandwidth rather than data loss, so it's recoverable — just not free.

#4. The command to be careful with

This one appears in every answer online and deletes more than most people realise:

docker system prune -a --volumes

--volumes removes volumes not currently attached to a running container. If a database container happens to be stopped at that moment, its data volume qualifies, and the data is gone with no undo. I've seen a development database lost this way by somebody following a snippet, and the tell is that the command appeared to work fine.

List what would go first:

docker volume ls -f dangling=true

Read that list. Satisfy yourself that nothing on it matters. Only then prune volumes. Anything holding real data belongs in a named volume with a backup, not in whatever the compose file generated.

#5. Stop it filling up again

Cap the logs. Container logs grow without limit by default, and a chatty service can produce gigabytes over weeks:

services:
  app:
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Prune on a schedule rather than in a crisis. A weekly docker builder prune -f --filter until=168h keeps the cache from compounding, and clearing it when nothing is broken is far less stressful than at the moment a deploy fails.

If you're pulling large model files, keep them in a mounted directory on the host rather than baking them into images. A layer holding a multi-gigabyte model is duplicated every time the image is rebuilt, and that pattern fills a disk faster than anything else in this guide.

#6. What I run, in order

docker system df. Read the reclaimable column. Then docker builder prune.

That sequence ends it most of the time, and nothing in it can lose data. I only move on if the reclaimable figure was small, which usually means the space is in images I still use or in a virtual disk that needs raising.

The step I skip now, having learned the hard way, is reaching for system prune with the volumes flag because it appeared in a search result. It works. It also deleted a colleague's local database once, and the command gave no warning that it was about to.

List before you delete. Every time. The 30 seconds it costs is the cheapest insurance in this guide.

#Match your symptom to the fix

What you're seeing Likely cause Go to
df -h shows space free Docker's own disk, or inodes 1 and 2
On Mac or Windows Virtual disk limit reached 1
Build cache in the tens of GB Accumulated layers 3
IUse% at 100 Out of inodes 2
Fills up again within days Unbounded logs 5

#When pruning didn't reclaim anything

Check for a running container holding the space. Images in use aren't removed by any prune, so a large image backing a running service stays regardless of what you run.

Look for files written inside a container rather than to a volume, too. Those land in the container's writable layer. They don't show up as a volume, and they disappear when the container is recreated. That makes them both a disk problem and a data loss waiting to happen. If a service is writing anything you care about, it belongs on a volume. If it's writing something you don't, it should probably be writing less.

Frequently asked questions

Why does df -h show free space when Docker is full?

Usually because Docker's storage is on a different volume, or on Mac and Windows inside a fixed-size virtual disk. Occasionally because the filesystem is out of inodes rather than bytes, which df -h doesn't show.

Is docker system prune safe?

Without --volumes it's reasonably safe — stopped containers, unused networks, dangling images and build cache. With --volumes it can delete the data of any container that happens to be stopped.

Will pruning break running containers?

No. Prune skips anything in use. The cost lands later, when you need an image you removed and have to pull it again.

How do I give Docker Desktop more space?

Raise the virtual disk size in Docker Desktop's resources settings. It's worth pruning first — a bigger disk fills up too, just more slowly.

Written by

Vemuri Abhiram

Founder & Editor

Vemuri Abhiram is the founder and editor of Underread, where he writes about AI tools, software, and practical technology. He covers hands-on tool reviews, detailed guides, product comparisons, and emerging technologies.

More from Underread, once a week.

The guides worth reading and the tests worth trusting. One email, every Friday.

No spam. Unsubscribe in one click.