Skip to content
Blog

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.

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

TaskCommandSafety Level
Check Disk Usagedocker system dfRead-only
Remove Dangling Imagesdocker image prune -fVery Safe
Remove All Unused Imagesdocker image prune -a -fSafe (requires re-downloading)
Remove Images Older than 24hdocker image prune -a -f --filter "until=24h"Safe & Targeted
Full System Cleanupdocker system prune -a -fHigh Impact

Regularly pruning dangling and aged unused images maintains host performance and eliminates disk exhaustion failures.