Docker cleanup script with dry run and confirmation

Docker never deletes anything on its own, so stopped containers, old image layers and build cache accumulate until the disk is full. docker system prune cleans up, but it is easy to run with one flag too many. This script shows what the prune will touch, refuses to do anything in dry-run mode, and asks before it deletes.

The script

Save it as docker-cleanup.sh and make it executable with chmod +x docker-cleanup.sh.

#!/usr/bin/env bash
set -euo pipefail

DRY_RUN=0
ALL=0
VOLUMES=0
YES=0

usage() {
  cat <<USAGE
Usage: $(basename "$0") [-n] [-a] [-v] [-y] [-h]

  -n   dry run: list what would be removed and exit
  -a   also remove all unused images, not only dangling ones
  -v   also remove unused volumes
  -y   do not ask for confirmation
  -h   show this help
USAGE
}

while getopts ":navyh" opt; do
  case "$opt" in
    n) DRY_RUN=1 ;;
    a) ALL=1 ;;
    v) VOLUMES=1 ;;
    y) YES=1 ;;
    h) usage; exit 0 ;;
    \?) usage >&2; exit 2 ;;
  esac
done

if ! command -v docker >/dev/null 2>&1; then
  echo "docker command not found" >&2
  exit 1
fi
if ! docker info >/dev/null 2>&1; then
  echo "cannot talk to the Docker daemon (is it running, are you in the docker group?)" >&2
  exit 1
fi

echo "Disk usage now:"
docker system df
echo

echo "Stopped containers:"
docker container ls -a --filter status=exited --filter status=created --format '  {{.ID}}  {{.Names}}  {{.Status}}'
echo

if (( ALL )); then
  echo "Images not used by any container (-a):"
  docker image ls --format '  {{.ID}}  {{.Repository}}:{{.Tag}}  {{.Size}}'
else
  echo "Dangling images:"
  docker image ls --filter dangling=true --format '  {{.ID}}  {{.Repository}}:{{.Tag}}  {{.Size}}'
fi
echo

if (( VOLUMES )); then
  echo "Unused volumes (-v):"
  docker volume ls --filter dangling=true --format '  {{.Name}}'
  echo
fi

echo "Unused networks:"
docker network ls --filter dangling=true --format '  {{.ID}}  {{.Name}}'
echo

args=(--force)
if (( ALL )); then
  args+=(--all)
fi
if (( VOLUMES )); then
  args+=(--volumes)
fi

if (( DRY_RUN )); then
  echo "Dry run. Would run: docker system prune ${args[*]}"
  exit 0
fi

if (( ! YES )); then
  read -r -p "Run 'docker system prune ${args[*]}'? [y/N] " answer
  if [[ "$answer" != [yY] ]]; then
    echo "Cancelled, nothing removed."
    exit 0
  fi
fi

docker system prune "${args[@]}"
echo
echo "Disk usage after:"
docker system df

How to use it

./docker-cleanup.sh -n
./docker-cleanup.sh
./docker-cleanup.sh -a -v
./docker-cleanup.sh -a -y

• -n prints the report and the exact prune command, then exits. Run this first.
• No flags: removes stopped containers, unused networks, dangling images and build cache after a y.
• -a: also removes every image that no container uses. The preview lists all images, since Docker has no filter for exactly that set; the images attached to running or stopped containers in the list will be kept.
• -v: also removes unused volumes. Careful: a database volume whose container you removed earlier counts as unused and will be deleted.
• -y skips the question, for cron jobs. Combine with -a only if you are sure images can be re-pulled.

What the script does

• set -euo pipefail stops on the first error, so a failed docker info never leads to a prune.
• docker system df before and after shows how much space was reclaimed.
• The listing commands use --filter and --format to show only the relevant objects in a compact form.
• Prune flags are collected in a bash array so the same list is both printed in the prompt and passed to the command.
• read -r -p asks a yes/no question; anything but y or Y cancels.

Official documentation

• docker system prune reference
• Prune unused Docker objects