Docker Prune

Docker hub

A family of Docker commands that remove unused objects — stopped containers, dangling images, unused volumes, unused networks — to recover disk space on the host. Essential maintenance on build machines where layers accumulate over time.

Docker Prune — Cleaning Up Unused Docker Objects

What Is Docker Prune in Simple Terms?

Docker accumulates disk usage over time: stopped containers that were never removed, old image layers from previous builds (dangling images), volumes no longer attached to any container, and networks no longer used. The prune commands clean all of this up.

On a busy build machine that builds Docker images dozens of times per day, disk usage can grow by gigabytes daily without regular pruning.

Bash

# See current disk usage
docker system df
# TYPE            TOTAL   ACTIVE   SIZE      RECLAIMABLE
# Images          15      4        4.2GB     2.8GB (66%)
# Containers      8       3        45MB      40MB
# Local Volumes   5       3        1.5GB     800MB
# Build Cache     -       -        2.1GB     2.1GB

Individual Prune Commands

Bash

# Remove all stopped containers
docker container prune
# Removes: containers with status Exited or Created
# Keeps: running containers
 
# Remove dangling images (untagged — from old builds)
docker image prune
# Removes: images with no tag (<none>:<none>)
# Keeps: tagged images
 
# Remove ALL unused images (not just dangling)
docker image prune -a
# Removes: any image not referenced by a running container
# Use carefully on production servers
 
# Remove unused volumes
docker volume prune
# Removes: volumes not attached to any container (running or stopped)
# WARNING: this permanently deletes data in those volumes
 
# Remove unused networks
docker network prune
# Removes: networks not used by any container
 
# Remove everything at once (containers, images, networks)
# Does NOT remove volumes unless -v flag added
docker system prune
 
# Remove everything including volumes (DANGEROUS)
docker system prune -a -v
# WARNING: deletes ALL unused volumes = data loss risk

Safe Pruning Patterns

Bash

# Safe daily prune — only removes stopped containers and dangling images
docker container prune -f && docker image prune -f
 
# Skip confirmation prompts for automation
docker container prune -f
docker image prune -f
docker network prune -f
 
# Prune images older than 48 hours
docker image prune -a --filter "until=48h"
 
# Add to crontab on build machines (run at 3am daily)
# 0 3 * * * docker container prune -f && docker image prune -f

What Is Safe to Prune

Bash

SAFE to prune:
  Stopped containers (docker container prune)
  Dangling images (docker image prune without -a)
  Unused networks (docker network prune)
  Build cache (docker builder prune)
 
CAREFUL:
  All unused images (docker image prune -a)
  -> removes images not currently running
  -> next pull will re-download them
 
DANGEROUS:
  Unused volumes (docker volume prune)
  -> permanent data deletion
  -> always verify before running

Tip
Run docker system df before any prune command to see exactly how much space each category is using. This helps you decide which prune commands will have the most impact and avoid accidentally deleting volumes that contain important data.

Common Mistake
Running docker system prune -a -v without checking which volumes exist. The -v flag removes ALL unused volumes — if a database volume is not attached to a running container at that moment (e.g., the database container is stopped for maintenance), the volume and all its data are permanently deleted.

Frequently Asked Questions

Why do Docker hosts accumulate so much unused disk space in the first place?

Every image build that doesn't get tagged (an intermediate layer replaced by a newer build, or an image whose tag was reused) becomes a 'dangling' image that still consumes disk but is no longer referenced by name. Stopped containers keep their writable layer on disk until explicitly removed, and unused volumes and networks pile up the same way — none of this is cleaned up automatically, which is why build servers running frequent CI jobs can fill their disks within days without a prune schedule.

What's the danger of running docker system prune -a carelessly?

The `-a` flag removes all unused images, not just dangling ones — including tagged images you might want cached for a quick pull later — and it also clears unused build cache, which can make your next several builds noticeably slower as everything rebuilds from scratch. On a shared build server, prune with an age filter (`--filter until=24h`) rather than nuking everything, and never run it with `--volumes` without confirming nothing important lives in an 'unused' one.