docker-disk-doctor 0.3.1
Safe, explain-first Docker disk usage inspector and cleanup tool
License: MIT
Requires Python: >=3.10
Keywords: docker, homelab, self-hosted, disk-usage, cli

# Docker Disk Doctor

![PyPI](https://img.shields.io/pypi/v/docker-disk-doctor)
![Python](https://img.shields.io/pypi/pyversions/docker-disk-doctor)
![License](https://img.shields.io/github/license/andreasrevdal/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:

```bash
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

<details>
<summary>Click to expand example output</summary>

![Docker Disk Doctor example output](docs/screenshot.png)

</details>

---

## Installation

### Prerequisites

You need `pipx`.

On most Debian / Ubuntu systems:

```bash
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

```bash
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:

```bash
sudo usermod -aG docker $USER
```

Then **log out and back in**, and verify:

```bash
docker ps
```

Once `docker ps` works, Docker Disk Doctor will work.

---

## Usage

### Show disk usage breakdown (default)

```bash
dockerdoctor
```

(or)

```bash
docker-disk-doctor
```

---

## Cleanup (optional)

Docker Disk Doctor is **safe-by-default**.

Nothing is deleted unless you explicitly confirm it.

### Preview cleanup (dry-run)

```bash
dockerdoctor test clean all
```

You can also preview specific targets:

```bash
dockerdoctor test clean images
dockerdoctor test clean volumes
```

### Apply cleanup

```bash
dockerdoctor clean all --yes
```

Or target specific resources:

```bash
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