flamedisk 🔥

Interactive disk-usage visualiser. Scan a directory and open a self-contained HTML report with a flame graph and sortable file tree — no server required.

Install

pip install flamedisk

Requires Python 3.9+. No runtime dependencies beyond the standard library.

Quick start

flamedisk /path/to/scan

The report opens in your default browser. The HTML file is fully self-contained — share it as a single file, no internet connection needed.

CLI

flamedisk [path] [options]

Examples

# Scan home directory and open in browser
flamedisk ~

# Save report without opening browser
flamedisk /var/log -o report.html -q

# Limit depth, skip small files
flamedisk /usr --depth 4 --min-size 1MB

# Skip virtual filesystems
flamedisk / --exclude proc sys dev -q

# Skip files by glob pattern (quote so the shell doesn't expand them)
flamedisk . --exclude '*.log' '*.tmp'

# Path with spaces
flamedisk "/home/My Documents"

# Exclude list followed by a spaced path
flamedisk --exclude .git node_modules -- "/my project"

# Pipe JSON tree to jq
flamedisk . --json | jq '.children[0]'

Python API

from flamedisk import scan, write_html

tree = scan(
    "/home/user",
    max_depth=5,
    exclude=[".git", "node_modules"],
    workers=16,
)
write_html(tree, "report.html")

See docs/api.md for the full API reference.

The report

Tree + Flame view (default)

The left panel shows an expandable file tree. The right panel shows a flame graph — each row is a depth level, each cell is a file or directory sized proportionally to disk usage. The root sits at the bottom; deeper entries grow upward.

Flame view

The flame graph fills the full window.

Zoom

Click any directory cell in the flame graph to zoom into it. The original colours and depth levels are preserved — the view rescales so the selected directory fills the full width. Press Esc or click ↺ Reset to return.

List view

Flat sortable list of the current directory's immediate children. Sort by Name, Size, or Type. The size bar and percentage column always show each entry's share of the total root directory.

Search

Type in the search box (top-right) to highlight matching entries across all views. Matching cells are highlighted; non-matching entries are dimmed.

Unreadable entries

If an entry can't be read during the scan — permission denied, a directory that vanished mid-scan, a stale network handle — flamedisk records it and keeps going rather than aborting. A ⚠ banner in the header shows how many entries were skipped; hover it for the full path and OS error of each. Affected rows in the tree carry a ⚠ marker, and selecting one shows the error in the status bar. Because the contents of a skipped entry are never counted, the totals shown understate actual disk usage by that amount.

Keyboard shortcuts

Install from source

git clone https://github.com/jrvannucci/flamedisk
cd flamedisk
pip install -e ".[dev]"

Development

pytest              # run the test suite
ruff check .        # lint

Tests run on Linux, macOS, and Windows across Python 3.9–3.13 in CI. Symlink tests skip automatically where the environment cannot create symlinks (Windows without Developer Mode).

License

MIT