Recipes

Scope: the jobs ncdu gets hired for, as short procedures. Each assumes the chapters before it; the dangerous steps say which chapter to reread.

"The root disk is full"

The classic page. Root filesystem only, cache counted (you may be about to delete it — you want it in the numbers):

$ ncdu -x /

Descend by size. The usual suspects are /var (logs, package caches), /usr (seldom guilty), /root and /home only if they share the filesystem — with -x, a separate /home mount shows the > flag and 0.0 B, which is the tool telling you it is not part of this question. When you find the directory, press i before d, and reread chapter 5 before any directory delete. On a production box, browse with -r first.

The before/after cleanup ledger

Chapter 6's workflow, as a habit:

$ ncdu -0 -o ~/snapshots/disk-2026-10-21-before.json /
$ ncdu /          (clean up, per chapter 5)
$ ncdu -0 -o ~/snapshots/disk-2026-10-21-after.json /

Browse the pair when someone asks what the cleanup actually recovered. The exports are a few hundred kilobytes for a home tree — the lab's is 2,920 bytes — so keeping dated snapshots costs nothing and ends arguments.

Scan there, browse here

A remote server with no room to sit in front of:

$ ssh server 'ncdu -o - /' > server-snapshot.json
$ ncdu -f server-snapshot.json

Full colour-free interactive browsing of a scan taken on another machine, with deleting impossible (chapter 6) — the safest way to plan a cleanup before the maintenance window opens.

The home-directory audit

Quarterly, ten minutes:

$ ncdu --exclude-caches ~

The total is your home without the parts you may delete blind; whatever tops the list is a real decision. Then quit, rerun without the flag, and the difference between the two footers is the size of "blind" this quarter — if the cache total shocks you, the tagged directories themselves (chapter 4) are the places to teach better habits.

Hunt the many-small-files directory

One huge file is easy. A million tiny ones fill disks and inodes while looking innocent by size:

$ ncdu ~     then C to sort by item count, c to show counts

In the lab the C ordering puts .cache (24 items) on top despite its modest 4.1 MiB. On a real tree, follow the item counts down: mail folders, node_modules, build trees and browser profiles are the usual nests. And remember chapter 3: each of those items costs a full block, so the disk-usage column already knows — counts tell you why.

Prove a file is sparse

Someone swears the 100 MiB image is "not really taking space":

$ ncdu homedir      (find it, then)
a                   apparent view: it jumps to the top
i                   the popup: both numbers, exact

Mirrored from outside with stat (chapter 3): size large, blocks zero (or far too few). The argument is over when both numbers are on one screen.

After any scan whose totals will drive a decision, look for ! flags before believing the footer — descend once through the top directories, or grep the export:

$ ncdu -0 -o scan.json /home
$ grep -c read_error scan.json

A nonzero count (chapter 9's specimen makes it 1) means unreadable corners; the totals omit them silently. Rescan as a user who can read them, or record the blind spot beside the number.

Keep a shrinking disk honest

A weekly dated export, automated:

# cron, Mondays 06:00
0 6 * * 1  ncdu -0 -o /var/backups/disk-$(date +\%F).json -x /

No screen, no interaction — -0 is built for this (chapter 4). Browse any week's file when "it filled up slowly, then all at once" needs a timeline. Mind the hardlink paragraph in chapter 6 before summing these with a script.