docker-disk-doctor 0.3.1

Safe, explain-first Docker disk usage inspector and cleanup tool

Docker Disk Doctor

Docker Disk Doctor is a safe, explain-first CLI tool that shows how Docker is using disk space and what is safe to clean — without blindly running docker system prune.

Built from real homelab and infrastructure pain.

---

Why this exists

Docker is great… until your disk suddenly fills up.

At that point, most people run:

docker system prune -a

…and hope for the best.

Docker Disk Doctor exists to answer one simple question before you delete anything:

What exactly is using my disk space, and what is safe to remove?

This tool is safe-by-default.
It explains first — you decide what to clean.

---

Features

• Full breakdown of Docker disk usage:
  • Images (used vs unused)
  • Containers (running vs stopped)
  • Volumes (attached vs orphaned)
• Actual disk usage (MB / GB)
• Clear, readable CLI tables
• Safe-by-default cleanup (nothing is deleted unless you explicitly confirm)
• Designed for homelabs, servers, and real systems

---

Screenshot

Click to expand example output

---

Installation

Prerequisites

You need pipx.

On most Debian / Ubuntu systems:

sudo apt update
sudo apt install -y pipx
pipx ensurepath

After pipx ensurepath, open a new terminal (or log out/in) so your PATH updates.

---

Install Docker Disk Doctor

pipx install docker-disk-doctor

This installs the dockerdoctor command (and also docker-disk-doctor).

---

Docker permission note (important)

If you get a Permission denied error to /var/run/docker.sock, your user likely can't access Docker.

Fix it with:

sudo usermod -aG docker $USER

Then log out and back in, and verify:

docker ps

Once docker ps works, Docker Disk Doctor will work.

---

Usage

Show disk usage breakdown (default)

dockerdoctor

(or)

docker-disk-doctor

---

Cleanup (optional)

Docker Disk Doctor is safe-by-default.

Nothing is deleted unless you explicitly confirm it.

Preview cleanup (dry-run)

dockerdoctor test clean all

You can also preview specific targets:

dockerdoctor test clean images
dockerdoctor test clean volumes

Apply cleanup

dockerdoctor clean all --yes

Or target specific resources:

dockerdoctor clean images --yes
dockerdoctor clean volumes --yes

The --yes flag is required to prevent accidental data loss.

---

Safety guarantees

• No automatic deletions
• No force-removal by default
• No surprises
• Docker may refuse to delete resources still in use — those are skipped safely

---

Support

If this tool saved you time, stress, or disk space,
consider buying me a compute ☕

https://buymeacoffee.com/revdal

---

License

MIT License