Disk Usage and Cleanup

Docker objects -- images, containers, volumes, and build cache -- accumulate over time. Without periodic cleanup, they can consume gigabytes of disk space. This lesson covers how to monitor usage, identify waste, and clean up safely.

Checking Disk Usage

Quick Summary

docker system df

TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          12        5         2.3GB     1.1GB (47%)
Containers      5         2         120MB     50MB (41%)
Local Volumes   3         1         500MB     0B (0%)
Build Cache     0         0         0B        0B

The RECLAIMABLE column shows how much space you can safely free.

Detailed Breakdown

# See per-image, per-container, per-volume sizes
docker system df -v

# See writable layer size per container
docker ps -s

What Takes Up Space

flowchart TD
    Docker["Docker Disk Usage"] --> Images["Images<br/>(old versions, dangling)"]
    Docker --> Containers["Containers<br/>(stopped containers,<br/>writable layers)"]
    Docker --> Volumes["Volumes<br/>(unused named volumes)"]
    Docker --> Cache["Build Cache<br/>(layer cache from builds)"]

    style Images fill:#e3f2fd,stroke:#1565c0
    style Containers fill:#fff3e0,stroke:#ef6c00
    style Volumes fill:#ffebee,stroke:#c62828
    style Cache fill:#f5f5f5,stroke:#9e9e9e

Source	What Accumulates	Risk Level
Old images	Previous versions after pulling updates	Low -- safe to prune
Dangling images	Untagged layers from rebuilds (tagged <none>)	Low -- safe to prune
Stopped containers	Containers you stopped but did not remove	Low -- safe to prune
Build cache	Cached layers from docker build	Low -- safe to prune
Unused volumes	Named volumes not attached to any container	High -- may contain data

Prune Commands

Docker provides prune commands for each object type:

Command	What It Deletes	Safe?
docker image prune	Dangling images (tagged <none>)	✓ Safe
docker image prune -a	All images not used by running containers	⚠ Removes pullable images
docker container prune	All stopped containers	✓ Safe
docker network prune	All unused networks	✓ Safe
docker volume prune	All unused volumes	❌ Dangerous -- can delete data
docker builder prune	Build cache	✓ Safe

The Master Command: docker system prune

Cleans up multiple types at once:

# Remove stopped containers, dangling images, unused networks, and build cache
docker system prune

The Nuclear Option

# Remove EVERYTHING not currently in use (including tagged images and volumes)
docker system prune -a --volumes

Extreme Caution

--volumes will delete your database data if the database container is stopped. Never put this in a cron job.

Safe Automated Cleanup

For build servers or CI environments, use time-based filtering:

# Remove items older than 24 hours
docker system prune -f --filter "until=24h"

This is safe for CI because it does not delete recently-built artifacts.

Monitoring Disk Over Time

Check	How Often	Command
Docker disk summary	Weekly	docker system df
Host disk space	Weekly	df -h
Largest log files	Monthly	sudo du -sh /var/lib/docker/containers/*/*-json.log | sort -rh | head
Unused volume check	Monthly	docker volume ls -f dangling=true

Key Takeaways

• Run docker system df weekly to understand where disk space is going.
• docker system prune is safe for routine cleanup (stopped containers, dangling images, build cache).
• Never use docker volume prune or --volumes without checking what volumes exist first -- it destroys data.
• Use --filter "until=24h" for automated CI cleanup to avoid deleting fresh builds.
• Combine Docker monitoring with host-level disk checks (df -h) for full visibility.

What's Next

• Continue to Updating Containers to learn how to upgrade running applications.