Metadata-Version: 2.4
Name: docker-disk-doctor
Version: 0.3.0
Summary: Safe, explain-first Docker disk usage inspector and cleanup tool
Author: Andreas Revdal
License: MIT
Keywords: docker,homelab,self-hosted,disk-usage,cli
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: docker>=7.0.0
Requires-Dist: rich>=13.0.0
Dynamic: license-file

# 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
```

> You may need to open a **new shell** after running `pipx ensurepath`.

---

### Install Docker Disk Doctor

Install directly from GitHub:

```bash
pipx install git+https://github.com/andreasrevdal/docker-disk-doctor.git
```

This installs the `dockerdoctor` command globally for your user.

> Note: The tool is currently installed directly from GitHub.  
> A PyPI release (`pipx install docker-disk-doctor`) may come later.

---

## Usage

### Show disk usage breakdown (default)

```bash
dockerdoctor
```

This will display:

- Used vs unused images
- Running vs stopped containers
- Attached vs orphaned volumes

No changes are made to your system.

---

## 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
