Docker System Prune — Reclaim Disk Space Guide

In this tutorial, you'll learn about Docker System Prune. We cover key concepts, practical examples, and best practices.

Docker consumes disk space quickly with dangling images, stopped containers, unused volumes, and build cache. Left unchecked, this fills your disk and causes build failures, container crashes, and system slowdowns.

The Problem

docker system df

Shows excessive usage:

TYPE                TOTAL     ACTIVE    SIZE          RECLAIMABLE
Images              47        5         12.3GB        9.8GB (79%)
Containers          34        3         2.1GB         1.9GB (90%)
Local Volumes       22        4         5.6GB         4.2GB (75%)
Build Cache         156       0         8.4GB         8.4GB (100%)

Wrong Approach

# WRONG — manual, slow, misses volumes and cache
docker rm $(docker ps -aq)
docker rmi $(docker images -q)

Right Approach

# Remove everything unused
docker system prune -a --volumes -f

Expected output:

Deleted Images:
deleted: sha256:a1b2c3d4...
deleted: sha256:f6e5d4c3...

Deleted Volumes:
deleted: volume_name

Total reclaimed space: 15.2GB

Step-by-Step Fix

Step 1: Check disk usage

docker system df

Step 2: Prune unused containers

docker container prune -f

Step 3: Prune dangling images

docker image prune -f

Step 4: Prune all unused images (not just dangling)

docker image prune -a -f

Step 5: Prune unused volumes

docker volume prune -f

Step 6: Prune build cache

docker builder prune -a -f

Step 7: Full cleanup

docker system prune -a --volumes -f

Step 8: Filter by age

docker system prune -a --filter "until=24h" -f

Step 9: Show reclaimable space

docker system df

Expected after cleanup:

TYPE                TOTAL     ACTIVE    SIZE    RECLAIMABLE
Images              5         5         2.5GB   0B
Containers          3         3         200MB   0B
Local Volumes       4         4         1.4GB   0B
Build Cache         0         0         0B      0B

Prevention Tips

• Run docker system prune -f --filter "until=24h" daily via cron
• Use --rm flag for temporary containers
• Set build cache limits in Docker BuildKit config
• Monitor disk with docker system df --format "{{.Size}}" in CI/CD
• Avoid keeping unused volumes after container removal

Common Mistakes with prune disk

1. Overlapping type class instances that cause GHC to reject the program with ambiguous dispatch errors
2. Non-exhaustive pattern matches that compile with warnings then crash at runtime
3. Misunderstanding that String is [Char] with poor performance for large text operations

These mistakes appear frequently in real-world DOCKER code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ