diskface 1.0.0

disk usage analyzer with live sorted results

diskface

A command-line disk & file usage analyzer with live, sorted results. It walks a directory (the current one by default), sizes every folder du-style, and shows the biggest ones as an expandable, numbered tree built with rich — then lets you pick nested folders to delete, or sweep temp files first.

By default it scans from the directory you're in, sizes folders recursively (a folder's size includes everything under it), and skips the regenerable "app junk" that clutters a real answer — node_modules, .git, .cache, __pycache__, virtualenvs, package caches, and so on. Only folders at or above your minimum size are shown.

---

Install

From PyPI (any OS):

pip install diskface        # or: pipx install diskface

Arch Linux (AUR):

yay -S diskface             # or your AUR helper of choice

Both give you a diskface command. The only runtime dependency is rich.

---

First run

On first launch in a terminal, diskface runs a short setup wizard and writes your answers to ~/.config/diskface/config.json. Just press enter to take the recommended default for each question. Re-run it any time with:

diskface --setup

To skip the wizard entirely (e.g. in scripts) and take defaults, pass --yes.

---

Usage

diskface [options]

Flag	Description
-m, --min-size <MB>	Minimum size for a folder/file to even show (default 100)
-t, --top <N>	How many results to show per level (default 20)
-R, --recursive / --shallow	Size folders du-style (default) vs. by their own files only
--tree / --flat	Show recursive results as a tree (default) or a flat leaderboard
--tree-depth <N>	How many folder levels to expand in the tree (default 3)
--depth <N>	Max scan depth to walk (0 = unlimited)
-f, --files / --dirs	Scan individual files instead of directories
-r, --root / --here	Scan from / (re-runs with sudo) instead of the cwd
-d, --hide-dotfiles	Skip dotfiles / dotfolders
-e, --exclude <pat>	Add an exclude pattern (repeatable)
--no-excludes	Ignore the built-in junk excludes
-c, --clean	Sweep temp files before scanning
-i / --no-interactive	Toggle the post-scan deletion prompt
--setup	(Re)run the interactive setup wizard
-y, --yes	Accept defaults, never prompt for setup
--config <path>	Use an alternate config file
-V, --version	Print version and exit

The tree numbers every folder it shows. When the deletion prompt appears, enter those numbers (comma-separated) to remove nested folders — each is confirmed before it's deleted.

Examples

diskface                       # recursive folder tree under the current directory
diskface --flat                # same sizes, flat top-N leaderboard instead of a tree
diskface --tree-depth 5 -m 500 # expand 5 levels deep, only folders >= 500 MB
diskface -f                    # largest individual files instead of folders
diskface --root                # whole system (elevates with sudo)
diskface -e '*.iso' -e backups # add extra excludes on top of the defaults
diskface --no-excludes         # show everything, junk included

Scan depth vs. accuracy

--depth bounds how deep diskface walks; --tree-depth bounds how deep the tree is shown. Folder totals are accurate for everything within the scan depth, so if a tree has very deep content, --depth 0 gives fully accurate du-style totals at the cost of a slower walk.

---

Excludes

Exclusions come from three places, combined at scan time:

1. Built-in app junk (APP_EXCLUDES in diskface.py) — matched by folder/file name anywhere in the tree. Disable with --no-excludes.
2. extra_excludes in your config — your own always-on additions.
3. -e/--exclude flags — one-off additions for a single run.

Matching rules: an entry without a slash matches a basename anywhere (node_modules, .cache, glob-aware); an entry with a slash matches the full path (/var/lib/docker, or **/foo for any .../foo). When scanning with --root, pseudo-filesystems like /proc, /sys, and /dev are always skipped.

---

Configuration

~/.config/diskface/config.json holds your saved defaults. Every value can be overridden by the matching CLI flag. A broken config is backed up and recreated automatically.

{
    "min_size_mb": 100,
    "top": 20,
    "max_depth": 8,
    "tree_depth": 3,
    "recursive": true,
    "tree_view": true,
    "scan_files": false,
    "hide_dotfiles": false,
    "interactive": true,
    "use_excludes": true,
    "extra_excludes": []
}

You can also add an optional "temp_paths": [...] array to override what --clean sweeps.

---

License

MIT.