diskface 1.1.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 drops you into an interactive folder browser — arrow keys to move, space to expand into a folder, d to delete it (confirmed, sizes re-roll up live). Think ncdu, but with diskface's junk-exclusion defaults. Progress and static output are rendered with rich; the browser is plain stdlib curses, so there are no extra dependencies.

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
--browse / --static	Interactive folder browser (default in a terminal) vs. printed tree
--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

Browser keys

Key	Action
↑/↓ or k/j	Move
space / enter / →	Expand into the highlighted folder (again to collapse)
←	Collapse, or jump back to the parent
d / Del	Delete the highlighted folder (asks first; sizes update live)
q / Esc	Quit (prints a summary of anything you freed)

With --static (or when output is piped) you get the printed numbered tree instead, and the deletion prompt takes those numbers comma-separated — each 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,
    "browse": true,
    "interactive": true,
    "use_excludes": true,
    "extra_excludes": []
}

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

---

License

MIT.