name: docker-cleanup description: Clean up Docker resources including volumes, containers, images, and networks. Use this skill when asked to "clean docker", "prune volumes", "remove unused containers", "free disk space from docker", "docker cleanup", "remove dangling images", or when troubleshooting Docker Desktop issues like unresponsive daemon, hanging commands, or VM problems. Covers volume pruning, identifying dangling/unused resources, container/image removal, Docker Desktop troubleshooting (restart procedures, VM issues), and system-wide cleanup.

Docker Cleanup

Quick Commands Reference

Troubleshooting Docker Desktop (macOS)

Symptoms of Unresponsive Docker

• Commands hang indefinitely (no output)
• docker info or docker ps never return
• Docker Desktop icon shows running but CLI unresponsive

Diagnostic Steps

1. Check if Docker processes are running:

pgrep -l -f "Docker"

2. Check Docker socket:

ls -la /var/run/docker.sock

3. Test basic connectivity:

docker version 2>&1

Resolution Steps

Restart Docker Desktop (GUI):

1. Click Docker icon in menu bar
2. Select "Restart" or "Quit Docker Desktop"
3. Reopen Docker Desktop
4. Wait for icon to stop animating (fully started)

Restart Docker Desktop (CLI):

# Quit Docker Desktop
osascript -e 'quit app "Docker"'

# Wait a moment
sleep 5

# Reopen Docker Desktop
open -a Docker

# Wait for startup (check with loop)
while ! docker info >/dev/null 2>&1; do
  echo "Waiting for Docker to start..."
  sleep 2
done
echo "Docker is ready"

Factory Reset (last resort):

1. Docker Desktop > Preferences > Reset > Reset to factory defaults
2. Warning: This removes all containers, images, and volumes

VM Issues

If Docker VM is corrupted:

# Stop Docker
osascript -e 'quit app "Docker"'

# Remove Docker VM files (careful!)
rm -rf ~/Library/Containers/com.docker.docker
rm -rf ~/Library/Group\ Containers/group.com.docker

# Restart Docker Desktop
open -a Docker

Cleanup Workflows

Safe Incremental Cleanup

Start conservative, escalate as needed:

# 1. Remove stopped containers
docker container prune -f

# 2. Remove dangling images (untagged)
docker image prune -f

# 3. Remove unused networks
docker network prune -f

# 4. Remove unused volumes (careful - data loss!)
docker volume prune -f

Aggressive Cleanup

For maximum space recovery (destructive):

# Remove everything unused: containers, networks, images, volumes
docker system prune -a --volumes -f

Inspect Before Removing

Check volume usage:

# List volumes with size (requires docker system df)
docker system df -v

# Inspect specific volume
docker volume inspect <volume_name>

Find what's using a volume:

docker ps -a --filter volume=<volume_name>

Check image layers:

docker history <image_name>

Selective Removal

Remove specific volumes:

docker volume rm volume1 volume2

Remove volumes matching pattern:

docker volume ls -q | grep "pattern" | xargs docker volume rm

Remove old containers (stopped > 24h ago):

docker container prune --filter "until=24h"

Remove images older than 7 days:

docker image prune -a --filter "until=168h"

Disk Space Analysis

# Overview of Docker disk usage
docker system df

# Detailed breakdown
docker system df -v

# Find large images
docker images --format "{{.Repository}}:{{.Tag}} {{.Size}}" | sort -k2 -h

Safety Notes

• docker volume prune removes all volumes not attached to containers - verify important data is backed up
• -f flag skips confirmation prompts - use carefully
• docker system prune -a removes all unused images, not just dangling ones
• Running containers and their resources are never affected by prune commands