The Nuclear Option: Complete Docker Cleanup Guide

uriByuri DevOps, Docker, GitHub

When You Need a Fresh Docker Start (And How to Safely Nuke Everything)

🚨 CRITICAL WARNING – READ THIS FIRST

This guide contains DESTRUCTIVE commands that will permanently delete ALL Docker data on your system.

You will lose:

  • ❌ ALL containers (running and stopped)
  • ❌ ALL Docker images (including custom builds)
  • ❌ ALL Docker volumes (databases, uploaded files, etc.)
  • ❌ ALL custom networks
  • ❌ ALL build cache
  • ❌ ALL development work stored in containers

⚠️ This is a NUCLEAR OPTION – use only when you want a completely clean slate.

Table of Contents

  1. When You Need This
  2. Before You Begin – Safety Checklist
  3. The Nuclear Cleanup Commands
  4. Understanding Each Step
  5. Alternative: One-Liner Approach
  6. Docker Compose Cleanup
  7. Verification Commands
  8. Recovery and Next Steps
  9. Advanced Tips and Automation

When You Need This

You Might Need This When…

  • Docker is consuming too much disk space
  • You have hundreds of old containers cluttering your system
  • Development environments are conflicting with each other
  • Docker Desktop is running slowly due to accumulated data
  • You’re following a tutorial that requires a “clean” Docker installation

Common Scenarios Include…

  • Preparing CI/CD environments for clean builds
  • Resetting development machines between projects
  • Cleaning up after extensive Docker experimentation
  • Resolving complex networking or volume conflicts
  • Preparing systems for Docker version upgrades

When NOT to Use This

  • ❌ You have production data in Docker containers
  • ❌ You have important databases in Docker volumes
  • ❌ You’re sharing the machine with other developers
  • ❌ You have custom images that took hours to build
  • ❌ You’re not sure what’s running on your Docker system

Safety Checklist

🛡️ MANDATORY STEPS – Do NOT Skip These

1. Backup Critical Data

# List all volumes to identify important data
docker volume ls

# Backup critical volumes (example for database)
docker run --rm -v myproject_db_data:/data -v $(pwd):/backup alpine tar czf /backup/database_backup.tar.gz -C /data .

# Export important images
docker save -o my-custom-app.tar my-custom-app:latest

2. Document Running Services

# List all running containers with their ports
docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Ports}}\t{{.Status}}"

# List all volumes and what they contain
docker volume ls
docker volume inspect volume_name

3. Check for Production Workloads

# Look for containers that might be production services
docker ps -a --filter "label=environment=production"
docker ps -a --filter "restart=unless-stopped"
docker ps -a --filter "restart=always"

4. Verify You’re on the Right Machine

# Make absolutely sure you're on your development machine
hostname
whoami
docker context ls  # Check which Docker context you're using

⚠️ Final Warning

Once you run these commands, there is no undo. Docker doesn’t have a recycle bin. If you’re not 100% certain, stop here and use selective cleanup commands instead.

Nuclear Cleanup

The Complete Destruction Sequence

Here’s the fastest way to completely wipe your Docker environment while keeping Docker itself installed:

# 1. Stop every running container (silently ignore if none)
docker stop $(docker ps -q) 2>/dev/null

# 2. Remove *all* containers (running or exited)
docker rm -f $(docker ps -aq) 2>/dev/null

# 3. Delete every image (dangling + tagged)
docker rmi -f $(docker images -aq) 2>/dev/null

# 4. Prune everything else—networks, build cache, and **volumes**
docker system prune --all --volumes --force

Copy-Paste Safety Version

If you want to see what each command will do before running it:

# Preview what will be stopped
echo "Containers that will be stopped:"
docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"

# Preview what will be removed
echo "All containers that will be deleted:"
docker ps -a --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"

echo "All images that will be deleted:"
docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"

echo "All volumes that will be deleted:"
docker volume ls

# If you're sure, run the nuclear sequence:
read -p "Are you ABSOLUTELY sure you want to delete everything? (type 'DELETE EVERYTHING'): " confirm
if [ "$confirm" = "DELETE EVERYTHING" ]; then
    docker stop $(docker ps -q) 2>/dev/null
    docker rm -f $(docker ps -aq) 2>/dev/null
    docker rmi -f $(docker images -aq) 2>/dev/null
    docker system prune --all --volumes --force
    echo "🧹 Nuclear cleanup complete!"
else
    echo "❌ Cleanup cancelled - nothing was deleted"
fi

Understanding Each Step

Step 1: Stop All Running Containers

docker stop $(docker ps -q) 2>/dev/null
  • What it does: Gracefully shuts down every running container
  • Why first: Allows containers to save state and close cleanly
  • Time: May take 10-30 seconds depending on container shutdown procedures
  • Beginners: Think of this as “closing all programs” before wiping your computer

Step 2: Force Remove All Containers

docker rm -f $(docker ps -aq) 2>/dev/null
  • What it does: Deletes every container (stopped and running)
  • Force flag: -f ensures even stuck containers are removed
  • Scope: -a means “all” containers, not just running ones
  • Point of no return: After this, all container data is gone forever

Step 3: Delete All Images

docker rmi -f $(docker images -aq) 2>/dev/null
  • What it does: Removes every Docker image from your system
  • Includes: Base images (ubuntu, nginx), custom builds, everything
  • Impact: You’ll need to re-download/rebuild images for future projects
  • Disk space: This usually frees the most space

Step 4: System-Wide Cleanup

docker system prune --all --volumes --force
  • Networks: Removes custom networks (keeps default ones)
  • Build cache: Clears Docker’s build layer cache
  • Volumes: ⚠️ DESTROYS ALL DATA in Docker volumes
  • Dangling objects: Cleans up any leftover resources

One-Liner Alternative

For those who prefer a single command:

docker stop $(docker ps -q) 2>/dev/null && docker system prune --all --volumes --force

Why this works:

  • system prune automatically removes stopped containers
  • The explicit stop ensures everything halts gracefully first
  • Shorter but equally destructive

Docker Compose Cleanup

If You Use Docker Compose Projects

Before running the nuclear cleanup, properly shut down Compose projects:

For Docker Compose v2 (Modern – Built into Docker)

# In each project directory:
docker compose down --remove-orphans --volumes

# Or from anywhere, if you know the project name:
docker compose -p myproject down --remove-orphans --volumes

For Docker Compose v1 (Legacy)

# In each project directory:
docker-compose down --remove-orphans --volumes

Find All Compose Projects

# List all compose projects
docker compose ls

# Or check for compose labels
docker ps -a --filter "label=com.docker.compose.project"

Automated Compose Cleanup Script

#!/bin/bash
# Save as cleanup-compose.sh

echo "🔍 Finding Docker Compose projects..."

# Get all unique compose project names
projects=$(docker ps -a --filter "label=com.docker.compose.project" --format "{{.Label \"com.docker.compose.project\"}}" | sort -u)

if [ -z "$projects" ]; then
    echo "No Docker Compose projects found."
else
    echo "Found projects: $projects"
    for project in $projects; do
        echo "🧹 Cleaning up project: $project"
        docker compose -p "$project" down --remove-orphans --volumes 2>/dev/null || true
    done
fi

echo "✅ Compose cleanup complete!"

Verification Commands

Confirm Everything is Gone

After running the nuclear cleanup, verify your system is clean:

# Should return empty or just headers
echo "=== CONTAINERS ==="
docker ps -a

echo "=== IMAGES ==="
docker images -a

echo "=== VOLUMES ==="
docker volume ls

echo "=== NETWORKS ==="
docker network ls

echo "=== DISK USAGE ==="
docker system df

Expected Results

  • Containers: No output (completely empty)
  • Images: No output (completely empty)
  • Volumes: Only shows the built-in “local” driver
  • Networks: Only default networks (bridge, host, none)
  • Disk usage: Should show 0 bytes for most categories

If Something Remains

# Force remove stubborn containers
docker container prune --force

# Force remove dangling images
docker image prune --all --force

# Remove unused networks
docker network prune --force

# Final system cleanup
docker builder prune --all --force

Recovery and Next Steps

After the Nuclear Cleanup

1. Verify Docker Still Works

# Test basic Docker functionality
docker run hello-world

# Should download and run successfully

2. Reconfigure Development Environment

# Reinstall base images you commonly use
docker pull ubuntu:latest
docker pull nginx:latest
docker pull mysql:8.0
docker pull node:18

# Or let your projects rebuild as needed

3. Restore from Backups (if any)

# Restore saved images
docker load -i my-custom-app.tar

# Restore volume data
docker volume create myproject_db_data
docker run --rm -v myproject_db_data:/data -v $(pwd):/backup alpine tar xzf /backup/database_backup.tar.gz -C /data

4. Restart Development Projects

# Navigate to project directories and rebuild
cd ~/projects/myapp
docker compose up -d --build

Advanced Tips and Automation

For CI/CD Environments

#!/bin/bash
# ci-docker-cleanup.sh - Safe for automated environments

set -e  # Exit on any error

echo "🧹 Starting CI Docker cleanup..."

# More targeted cleanup for CI
docker container prune --force --filter "until=24h"
docker image prune --all --force --filter "until=48h"
docker volume prune --force --filter "label!=keep"
docker network prune --force

# Keep frequently used base images
docker pull ubuntu:latest || true
docker pull alpine:latest || true

echo "✅ CI cleanup complete!"

Scheduled Cleanup (Cron Job)

# Add to crontab (crontab -e)
# Run cleanup every Sunday at 2 AM
0 2 * * 0 /path/to/docker-cleanup.sh >> /var/log/docker-cleanup.log 2>&1

Disk Space Monitoring

#!/bin/bash
# docker-space-check.sh

# Get Docker disk usage
usage=$(docker system df --format "table {{.Type}}\t{{.Size}}" | tail -n +2 | awk '{total += $2} END {print total}')

# Alert if over 10GB
if [ "$usage" -gt 10000000000 ]; then
    echo "⚠️ Docker using ${usage}GB - consider cleanup"
    docker system df
fi

Selective Cleanup (Safer Alternative)

Instead of nuclear cleanup, consider selective approaches:

# Remove only exited containers
docker container prune --force

# Remove only dangling images
docker image prune --force

# Remove only unused volumes (keeps named volumes)
docker volume prune --force

# Remove only unused networks
docker network prune --force

# Remove build cache older than 24h
docker builder prune --keep-storage 1GB --force

Troubleshooting

Common Issues After Nuclear Cleanup

1. “Permission Denied” Errors

# Reset Docker daemon (Linux)
sudo systemctl restart docker

# Or restart Docker Desktop (macOS/Windows)

2. “No Such Network” Errors

# Recreate default networks
docker network create bridge || true

3. “Volume Mount” Errors

# Recreate required volumes
docker volume create myproject_data

4. Build Cache Issues

# Force rebuild without cache
docker build --no-cache .
docker compose build --no-cache

Final Warnings and Disclaimers

  • Data Loss: These commands WILL destroy data permanently
  • Production Risk: NEVER run these on production systems
  • Backup Responsibility: Always backup critical data first
  • Team Impact: Coordinate with team members on shared systems
  • Learning Tool: Best used for learning and development environments

When to Seek Help

  • Shared Systems: If others use the same Docker installation
  • Production Data: If any containers contain production data
  • Complex Setups: If you have intricate networking or volume setups
  • Uncertainty: If you’re not sure what containers are doing

Alternative Resources

Conclusion

The nuclear Docker cleanup is a powerful tool for getting a completely fresh start, but it comes with significant risks. Use it judiciously, always backup important data, and consider whether selective cleanup might meet your needs with less risk.

Remember: Docker is a tool to make development easier. If managing Docker becomes more complex than the applications you’re building, it might be time to step back and simplify your approach.

Stay safe, backup often, and happy containerizing! 🐳

This guide is provided for educational purposes. The authors are not responsible for any data loss resulting from following these instructions. Always test commands in safe environments before using them on important systems.