Skip to content

Ncdu for Mere Mortals

Every disk eventually asks the same question: I'm full — what ate me? The answer is never one file; it is a tree — a downloads folder that kept everything, a cache that grew a little every day. ncdu is the terminal tool that answers it interactively: it scans a tree once, adds up the sizes per directory, biggest first, and then lets you climb down into the heavy branches and ask again.

ncdu's whole subject is one distinction most tools blur: a file has two sizes, the content and the space. A one-byte file costs a full disk block; a 100 MiB sparse file can cost nothing at all; a photograph with two names is counted once, though it displays twice. This guide takes those three specimens apart, teaches the scan options that change what "the total" means, gives deleting the plain treatment it deserves — no undo, no trash, one confirmation for a whole tree — and shows how to export a scan to a file and browse it later, on another machine, like a photograph of the disk.

The lab is one specimen home directory, built by a script in examples/ (build-tree.sh): installers and videos of exact sizes, a twenty-file cache, a hardlinked photo, a sparse disk image, a file with a space in its name, symlinks, an empty directory. Every name is invented and every size is deliberate.

A note on how this guide was verified. Two builds were run against the lab: ncdu 1.19 (the distro package) as the primary and ncdu 2.9 (the upstream static build) as cross-check — every screen, key, dialog and export in the chapters is a capture from one of them, driven in a real terminal. Where the two versions differ, the chapters say so in place, and criteria.md keeps the ledger of what is documented-only.

What this guide covers

  • What ncdu is — the question, scan then browse, the two sizes, versions 1.x and 2.x, where it runs, the lab
  • Reading the screen — the browser's anatomy, the movement and sorting keys, the display toggles, the flags, the info popup, the help screen, and refreshing a stale scan
  • Sizes on disk — blocks and rounding, the one-byte file, the sparse file, the file with two names, and reconciling three honest totals
  • Scanning options — one filesystem only, excluding by pattern and by cache tag, symlinks followed and not, read-only, extended info
  • Deleting — the confirmation dialog and its defaults, unlink underneath, the deletions that free nothing, and working habits
  • Exports and reports — scan now, browse later; the JSON format read closely (including its hardlink trap); the 2.x binary and compressed formats and which versions can read what
  • Recipes — full-disk triage, the before/after ledger, scan there browse here, the home audit, the many-small-files hunt, blind-spot checks
  • The neighbours — du first, then dust, dua and gdu, the graphical tools, and the macOS and Windows natives
  • Troubleshooting — totals that don't add up, deletions that free nothing, the ! flag, scripts that need -0, and unreadable exports
  • Glossary — the terms, collected in one place

What it doesn't cover

Making space by other means — compressing, archiving and moving data belong to the sibling guides on tar and archives and on watching your system; this one finds where the space went and, carefully, removes files. Recovering deleted files is a different trade entirely: ncdu's deleting is final, and chapter 5 says so in the plain terms it requires. Filesystem repair and quota administration are likewise elsewhere. And the full option reference is the man page: this guide teaches the everyday set and names the rest.

How to use this guide

Read chapter 1, build the lab tree as it directs, and keep a terminal open from chapter 2 on. Work in the lab and in a throwaway copy of it — chapter 5 deletes files on purpose, in the copy only, and the specimens should survive your experiments so you can start a chapter over. Graduate to your real home directory for looking whenever you like (looking cannot change anything), and to real deleting only after chapter 5. Keep the tree afterward: a filesystem with known answers is a standing rehearsal for the day a real one asks the same questions.

Fixture rebuild safety

The fixture builder creates a new target directory. It replaces an existing target only when a completed-build marker sits beside it (homedir.mere-mortals-fixture for a tree named homedir). Existing unmarked directories, symlink targets, protected home/current/script directories and overlapping builds are refused. Older fixture trees have no marker: use a fresh directory name and inspect the old tree manually. Do not add a marker to an unrelated directory. A failed or interrupted build may leave an unmarked tree or stale .build-lock directory; inspect it before cleaning up.

Part of the series

This guide is one of the For Mere Mortals guides: plain-language guides to the tools programmers and makers use.

Related guides:

License

The writing in this guide is licensed under CC BY 4.0. Code examples and lab scripts are licensed under the MIT License.