$ Linux One Liners
Back to problems

problem hub

Read-only first

Docker disk full on Linux

Measure Docker image, container, volume, and build-cache usage before pruning anything that may hold data.

Safest first command

docker system df -v

Before you run this

Expected output: Docker disk usage split by images, containers, local volumes, and build cache, including reclaimable estimates when Docker can calculate them.

When not to use it: Do not start from prune commands on production hosts, CI runners, or database/container-volume hosts until you know whether volumes hold persistent data.

Expected output example

TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          18        7         12.4GB    5.1GB (41%)
Containers      14        3         2.6GB     1.9GB (73%)
Local Volumes   9         6         42.0GB    4.0GB (9%)
Build Cache     31        0         8.8GB     8.8GB

How to read the result

Separate reclaimable image/cache space from named volumes. A large reclaimable percentage is only a cleanup candidate; named volumes may be databases, uploads, or application state.

What to check next

Build cache is the largest reclaimable class

Means: Old build layers are likely the main pressure source.

Next step: Inspect build cache and CI retention before pruning.

Summarize Docker Disk Usage

Local volumes dominate usage

Means: Persistent application data, databases, or uploads may live there.

Next step: Map volumes to containers before removing anything.

Show Containers in a Clean Triage Table

Container logs grew large under /var/lib/docker

Means: A noisy container may be filling host disk through JSON logs.

Next step: Read recent container logs and identify the noisy service before truncating or rotating.

Read Recent Container Logs

Docker disk-full decision tree

Start with Docker's own accounting, then decide whether pressure is images, stopped containers, volumes, build cache, or container logs. Treat volumes as data until proven otherwise.

  1. docker system df -v
  2. docker ps -a --format 'table {{.Names}}\t{{.Status}}\t{{.Image}}\t{{.Ports}}'
  3. docker logs --since 10m --tail 100 api

Volumes are not cache

A named or anonymous volume can contain a database, uploads, queues, or application state. Map volume ownership before deleting or pruning.

  1. docker ps -a --format 'table {{.Names}}\t{{.Status}}\t{{.Image}}'
  2. docker inspect web

Bad fixes to avoid

Do not run docker system prune -a or docker volume prune as a first response. Do not delete files manually under /var/lib/docker. Do not remove volumes until the owning container and backup/rollback path are clear.

Image, container, volume, and build-cache split

Docker disk usage is not one bucket. Images and build cache are usually safer cleanup candidates than volumes. Volumes may hold databases, uploads, queues, or application state.

  1. docker system df -v
  2. docker ps -a --format 'table {{.Names}}\t{{.Status}}\t{{.Image}}\t{{.Ports}}'

Safe prune notes

Treat prune commands as deletion commands. There is no universal preview that proves a prune is safe for your workload. Map containers, images, and volumes first, then choose the narrowest cleanup command.

  1. docker system df -v
  2. docker ps -a
  3. docker volume ls

Volume and build-cache safety branch

Separate reclaimable build cache from named volumes before pruning. Volumes may contain databases, uploads, or state that does not belong to an image cleanup task.

  1. docker system df -v
  2. docker ps -a --format 'table {{.Names}}\t{{.Status}}\t{{.Size}}'
  3. docker volume ls

Never delete overlay2 manually

Do not remove files under /var/lib/docker/overlay2 by hand. Use Docker-aware inspection and cleanup so Docker metadata stays consistent.

Common causes

  • Unused images and build cache
  • Stopped containers retaining writable layers
  • Container logs growing under Docker storage
  • Named volumes holding application data
  • CI builds pulling many tags

What not to change yet

  • Do not prune volumes before mapping ownership.
  • Do not manually delete files in /var/lib/docker.
  • Do not prune all images on a host that may need rollback tags.
  • Do not ignore the host-level df -h mount point.

Stop and escalate if

  • The next step could interrupt users, remove data, or lock out access.
  • The output includes secrets, customer data, or private infrastructure details.
  • You cannot explain the blast radius of the repair command.

platform notes

Distro and service notes

Docker

Docker cleanup commands can delete rollback images and stopped containers; inspect ownership first.

Storage

The host filesystem may be full even when Docker reclaimable space is low.

Logs

Noisy container logs need rotation or application fixes after the immediate incident.

supporting commands

Command path

Guides and drills