docker-cleanup-bot

CLI to prune dangling images, stopped containers, and unused volumes/networks. Includes dry-run safety and age-based filtering.

---

---

Features

• 🔍 Dry-run by default — always shows what would be deleted before acting
• 🗂 Cleans containers, images, volumes, and networks independently
• ⏱ Age-based filtering (--older-than 7d) — don't touch recent objects
• 📦 Keep-last policy (--keep-last 3) — retain the N most recent image tags
• 📊 Space reclaim summary (human-readable sizes)
• 🖥 status subcommand shows total Docker disk usage at a glance
• 📋 JSON output mode for CI pipeline integration

---

Usage

# Install
pip install docker-cleanup-bot

# Preview what would be cleaned (safe, no deletions)
docker-cleanup clean --dry-run

# Preview only images and containers, skip volumes
docker-cleanup clean --dry-run --no-volumes --no-networks

# Delete everything older than 7 days (with confirmation prompt)
docker-cleanup clean --older-than 7d

# Keep only the 3 most recent tags per image repo
docker-cleanup clean --keep-last 3 --dry-run

# Skip confirmation (for CI pipelines)
docker-cleanup clean --older-than 24h --force

# Show overall Docker disk usage
docker-cleanup status

---

📦 Installation

pip install docker-cleanup-bot

Or from source:

git clone https://github.com/your-username/docker-cleanup-bot.git
cd docker-cleanup-bot
pip install -e .

---

🔧 Usage

Commands:
  clean   Scan and remove unused Docker resources.
  status  Show current Docker disk usage.

Options for `clean`:
  --dry-run               Preview without deleting. [default: False]
  --images/--no-images    Include dangling/unused images.
  --containers/--no-containers  Include stopped containers.
  --volumes/--no-volumes  Include unused volumes.
  --networks/--no-networks Include unused networks.
  --older-than DURATION   Only objects older than this (e.g. 24h, 7d).
  --keep-last N           Keep N most recent image tags per repository.
  --force, -f             Skip confirmation prompt.
  --json                  JSON output for CI pipelines.

---

🤖 CI/CD Integration

# .github/workflows/cleanup.yml
- name: Docker Cleanup
  run: |
    pip install docker-cleanup-bot
    docker-cleanup clean --older-than 24h --force --json

---

🔒 Safety

• Never deletes running containers
• Never deletes built-in networks (bridge, host, none)
• Always shows a confirmation prompt unless --force is passed
• --dry-run mode is 100% read-only

---

🤝 Contributing

Pull requests are welcome. For major changes, please open an issue first.

---

📝 License

MIT © Danilo Vera