Pruning Dangling and Unused Docker Images Safely
Automating disk cleanup in Docker environments, distinguishing dangling layers from unused images, safely running docker image prune, and implementing automated cron maintenance.
Published on • November 18, 2026
AI Assistant

Over time, active Docker hosts, build nodes, and developer workstations accumulate gigabytes of stale container data. Running out of disk space (no space left on device) is one of the most common causes of Docker daemon outages and failed CI runner builds.
To reclaim storage safely, Docker provides the docker image prune and docker system prune subcommands.
In this tutorial, we will learn the difference between dangling images and unused images, how to execute targeted prune operations, and how to automate cleanup routines safely.
Dangling Images vs Unused Images
Before deleting local images, it is important to distinguish between these two classifications:
+-----------------------------------------------------------------------------------+
| 1. DANGLING IMAGES (<none>:<none>) |
| - Un-tagged intermediate build layers or old images replaced by a new build. |
| - Safe to delete at almost any time! |
+-----------------------------------------------------------------------------------+
| 2. UNUSED IMAGES |
| - Tagged images (e.g., redis:alpine, ubuntu:20.04) that are NOT currently |
| referenced by any running or stopped container on the host. |
| - May be needed for future offline work or build layer caching! |
+-----------------------------------------------------------------------------------+
Measuring Current Storage Footprint
Before running cleanup commands, check how much disk space is consumed by containers, images, volumes, and build caches:
docker system df
Sample output:
TYPE TOTAL ACTIVE SIZE RECLAIMABLE
Images 18 4 4.12GB 2.85GB (69%)
Containers 5 2 120MB 45MB (37%)
Local Volumes 3 3 1.1GB 0B (0%)
Build Cache 42 0 6.5GB 6.5GB (100%)
To see detailed breakdowns for individual images:
docker system df -v
Targeted Prune Workflows
1. Pruning Only Dangling Images
By default, docker image prune removes only dangling images (untagged <none>:<none> layers):
docker image prune
To bypass the interactive y/N prompt in scripts:
docker image prune -f
2. Pruning ALL Unused Images
To delete all tagged images that are not associated with at least one existing container (running or stopped), add the -a / --all flag:
docker image prune -a -f
(Warning: This will delete base images like alpine or ubuntu if no active container currently uses them, requiring them to be re-downloaded during the next build).
3. Filtering Prune Operations by Age or Label
You can apply --filter conditions to prevent deleting recently pulled images or preserve specific tagged categories:
# Delete unused images created more than 48 hours ago (until=48h)
docker image prune -a --filter "until=48h" -f
# Delete images without a specific preservation label
docker image prune -a --filter "label!=keep=true" -f
System-Wide Cleanup with docker system prune
To clean up stopped containers, dangling images, unused networks, and build caches simultaneously:
docker system prune -f
To include unused tagged images as well:
docker system prune -a --volumes -f
(Note: Adding --volumes will delete unattached persistent volumes! Only use --volumes if you are certain no critical database state resides in unattached volumes).
Automating Safe Cleanup on CI Runners and Servers
System administrators should schedule periodic cleanup jobs to prevent disk exhaustion on CI build servers.
Recommended Systemd Service or Cron Job
Create an automated cron script /etc/cron.daily/docker-clean:
#!/usr/bin/env bash
set -euo pipefail
# 1. Remove stopped containers older than 24 hours
docker container prune -f --filter "until=24h"
# 2. Remove unused images older than 7 days (preserves active build cache)
docker image prune -a -f --filter "until=168h"
# 3. Clear build cache older than 7 days
docker builder prune -f --filter "until=168h"
Make the script executable:
chmod +x /etc/cron.daily/docker-clean
Summary & Command Cheatsheet
| Task | Command | Safety Level |
|---|---|---|
| Check Disk Usage | docker system df | Read-only |
| Remove Dangling Images | docker image prune -f | Very Safe |
| Remove All Unused Images | docker image prune -a -f | Safe (requires re-downloading) |
| Remove Images Older than 24h | docker image prune -a -f --filter "until=24h" | Safe & Targeted |
| Full System Cleanup | docker system prune -a -f | High Impact |
Regularly pruning dangling and aged unused images maintains host performance and eliminates disk exhaustion failures.