Docker: Prune Unused Resources

Overview

Removes unused Docker resources to free up disk space and clean up the Docker environment. This includes stopped containers, dangling images, unused networks, and build cache. The operation is safe and only removes resources not currently in use.

Prerequisites

• Docker Engine installed and running
• Sufficient permissions to run Docker commands
• No critical containers running (verify first)

Usage

Basic Usage

.github/skills/docker-prune-scripts/run.sh

Via Skill Runner

.github/skills/scripts/skill-runner.sh docker-prune

Via VS Code Task

Use the task: Docker: Prune Unused Resources

Parameters

This skill uses Docker's default prune behavior (safe mode). No parameters accepted.

Environment Variables

This skill requires no environment variables.

Outputs

• Success Exit Code: 0
• Error Exit Codes: Non-zero on failure
• Console Output: List of removed resources and space reclaimed

Output Example

Deleted Containers:
f8d1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab

Deleted Networks:
charon-test_default
old-network_default

Deleted Images:
untagged: myimage@sha256:abcdef1234567890...
deleted: sha256:1234567890abcdef...

Deleted build cache objects:
abcd1234
efgh5678

Total reclaimed space: 2.5GB

What Gets Removed

The docker system prune -f command removes:

1. Stopped Containers: Containers not currently running
2. Dangling Images: Images with no tag (intermediate layers)
3. Unused Networks: Networks with no connected containers
4. Build Cache: Cached layers from image builds

What Gets Preserved

This command DOES NOT remove:

• Running Containers: Active containers are untouched
• Tagged Images: Images with tags are preserved
• Volumes: Data volumes are never removed
• Used Networks: Networks with connected containers
• Active Build Cache: Cache for recent builds

Safety Features

• Force Flag (-f): Skips confirmation prompt (safe for automation)
• Safe by Default: Only removes truly unused resources
• Volume Protection: Volumes require separate docker volume prune command
• Running Container Protection: Cannot remove active containers

Examples

Example 1: Regular Cleanup

# Clean up Docker environment
.github/skills/docker-prune-scripts/run.sh

Example 2: Check Disk Usage Before/After

# Check current usage
docker system df

# Run cleanup
.github/skills/docker-prune-scripts/run.sh

# Verify freed space
docker system df

Example 3: Aggressive Cleanup (Manual)

# Standard prune
.github/skills/docker-prune-scripts/run.sh

# Additionally prune volumes (WARNING: data loss)
docker volume prune -f

# Remove all unused images (not just dangling)
docker image prune -a -f

Disk Space Analysis

Check Docker disk usage:

# Summary view
docker system df

# Detailed view
docker system df -v

Output shows:

• Images: Total size of cached images
• Containers: Size of container writable layers
• Local Volumes: Size of data volumes
• Build Cache: Size of cached build layers

When to Use This Skill

Use this skill when:

• Disk space is running low
• After development cycles (many builds)
• After running integration tests
• Before system backup/snapshot
• As part of regular maintenance
• After Docker image experiments

Frequency Recommendations

• Daily: For active development machines
• Weekly: For CI/CD build servers
• Monthly: For production servers (cautiously)
• On-Demand: When disk space is low

Error Handling

Common issues and solutions:

Permission Denied

Error: permission denied

Solution: Add user to docker group or use sudo

Daemon Not Running

Error: Cannot connect to Docker daemon

Solution: Start Docker service

Resource in Use

Error: resource is in use

This is normal - only unused resources are removed

Advanced Cleanup Options

For more aggressive cleanup:

Remove All Unused Images

docker image prune -a -f

Remove Unused Volumes (DANGER: Data Loss)

docker volume prune -f

Complete System Prune (DANGER)

docker system prune -a --volumes -f

Related Skills

• docker-stop-dev - Stop containers before cleanup
• docker-start-dev - Restart after cleanup
• utility-clear-go-cache - Clear Go build cache

Notes

• Idempotent: Safe to run multiple times
• Low Risk: Only removes unused resources
• No Data Loss: Volumes are protected by default
• Fast Execution: Typically completes in seconds
• No Network Required: Local operation only
• Not CI/CD Safe: Can interfere with parallel builds
• Build Cache: May slow down next build if cache is cleared

Disk Space Recovery

Typical space recovery by resource type:

• Stopped Containers: 10-100 MB each
• Dangling Images: 100 MB - 2 GB total
• Build Cache: 1-10 GB (if many builds)
• Unused Networks: Negligible space

Troubleshooting

No Space Freed

• Check for running containers: docker ps
• Verify images are untagged: docker images -f "dangling=true"
• Check volume usage: docker volume ls

Space Still Low After Prune

• Use aggressive pruning (see Advanced Cleanup)
• Check non-Docker disk usage: df -h
• Consider increasing disk allocation

Container Won't Be Removed

• Check if container is running: docker ps
• Stop container first: docker stop container_name
• Force removal: docker rm -f container_name

---

Last Updated: 2025-12-20 Maintained by: Charon Project Docker Command: docker system prune -f