Interactive disk usage explorer
- Parallel scanning — scans your filesystem with 12 concurrent workers for fast results on large trees
- Real-time streaming — directory sizes stream to the browser live via Server-Sent Events (SSE) as the scan progresses
- Persistent cache with background refresh — previously scanned paths load instantly; stale data is refreshed in the background without blocking the UI
- Zoomable D3.js treemap — navigate disk usage visually; click any node to zoom in and explore
- Breadcrumb navigation — always know where you are in the tree and jump back to any ancestor in one click
- Per-folder refresh — re-scan any individual folder on demand without restarting the server
- Path jump bar — type any absolute path to jump directly to it
- Zero Python dependencies — runs entirely on the standard library; no
pip installrequired
- Python 3.8 or later
- macOS or Linux
- A modern web browser (Chrome, Firefox, Safari, or Edge)
git clone https://github.com/johnib/disko.git
cd disko
python3 disko.pydisko will start a local web server and open your browser automatically.
python3 disko.py [OPTIONS]
| Option | Default | Description |
|---|---|---|
--port PORT |
8080 |
Port for the local web server |
--path PATH |
$HOME |
Root directory to scan |
--no-browser |
— | Start the server without opening a browser tab |
--help |
— | Show help and exit |
Examples:
# Scan a specific directory on a custom port
python3 disko.py --path /var/log --port 9000
# Run headlessly (useful in SSH sessions)
python3 disko.py --path /data --no-browser- Scanning —
concurrent.futures.ThreadPoolExecutor(12 workers) walks the directory tree in parallel, collecting file sizes. - Streaming — as each directory is sized, the result is pushed to the browser over an SSE (
text/event-stream) connection so the treemap updates in real time. - Visualization — the browser renders an interactive, zoomable treemap using D3.js. Node area is proportional to disk usage.
- Cache — completed scan results are serialized to JSON and written to
~/.disko_cache.json. On subsequent runs, the cached data is served immediately while a background refresh runs concurrently.
| Detail | Value |
|---|---|
| Location | ~/.disko_cache.json |
| Version control | git-ignored by default |
| Clear cache | rm ~/.disko_cache.json |
The cache stores one entry per scanned root path. Entries are keyed by absolute path and include a timestamp used to determine staleness.
Contributions are welcome. Please read CONTRIBUTING.md for guidelines on how to open issues, submit pull requests, and run the test suite.
MIT License. Copyright (c) Jonathan Barazany.
See LICENSE for the full text.