ncdu Command: Tutorial & Examples

A disk-usage explorer you can walk through with arrow keys — the fastest way to answer "what filled up my server?"

What It Is

ncdu — NCurses Disk Usage — scans a directory tree and hands you a sorted, navigable map of what's using space, biggest first, that you steer with the arrow keys. It does the same job as du, but where du dumps a wall of numbers you then have to squint at and re-run, ncdu lets you walk into the big directory, see what's inside, walk into the next one, and delete the offender on the spot. When a disk fills up at 3am and you have ninety seconds to find the culprit, this is the tool.

It's not installed by default on most systems (apt install ncdu / dnf install ncdu), but it's tiny and worth having on every box you run. It's safe — scanning only reads — though it can delete files if you press d, so it's the one tool here with a real edit power, which we'll treat carefully. If you've never used it, the first time you watch yourself drill from "the disk is full" to "oh, it's 40 GB of old logs in /var/log" in three keystrokes, it becomes muscle memory immediately.

Your First Look

Point it at a directory (or / for the whole filesystem) and give it a second to scan:

ncdu /var

ncdu 1.18 ~ Use the arrow keys to navigate, press ? for help
--- /var --------------------------------------------------------
   42.1 GiB [##########] /log
    8.7 GiB [##        ] /lib
    3.2 GiB [          ] /cache
  612.0 MiB [          ] /backups
   44.0 KiB [          ] /tmp
@   0.0   B [          ]  some-broken-symlink

Each line is a child of the directory you're in, sorted largest-first, with a size, a little ASCII bar showing its share of the parent, and the name. The directory holding the most space floats to the top — here, /log is the obvious hog at 42 GiB. Press Enter (or →) to descend into it, ← to go back up, and keep following the biggest bar down the tree until you reach the actual files. That drill-down — always chasing the fattest bar — is the entire technique.

How I Read It

The mental model is dead simple and it's why ncdu beats du for this job: always follow the biggest bar. I start at the top of the tree (often ncdu /), look at which child has the longest [##########] bar, press Enter to go inside it, and repeat. Three or four hops and I'm standing on the exact directory — usually /var/log, a runaway database data dir, a forgotten /backups, or someone's 30 GB of core dumps — that ate the disk.

The thing I check before deleting anything is the difference between apparent size and disk usage. Press a to toggle: by default ncdu shows space actually consumed on disk (what df cares about), which accounts for filesystem block rounding and is the number that matters when you're out of room. And one habit that has saved me real embarrassment: ncdu shows you where the space is, but a file being big doesn't mean it's safe to delete — I confirm what a file is (often it's an active log or a database) before I ever press d.

The Screen, Explained

Everything on a row, left to right:

The size — 42.1 GiB, the total space this entry uses (the whole subtree, if it's a directory). This is the number you're hunting.
The bar — [##########], a visual share of the current directory's total. Ten hashes means "basically all of it"; an empty bar means a rounding error next to its siblings. Great for instantly seeing whether one thing dominates or space is spread thin.
The name — a leading / marks a directory; plain text is a file.
Leading flags — a @ marks a symlink, e an empty directory, > a directory ncdu couldn't enter (permissions), ! a read error. These tell you when a number might be incomplete.

At the very top, the header shows the version, a one-line hint, and the path you're currently inside. The bottom status line shows totals and any messages.

Reading It by Example

One child with a full [##########] bar, everything else empty. The clean case: space is concentrated. Press Enter and chase it down — you'll reach the culprit in seconds.

/log at 42 GiB inside /var. The single most common server "disk full." Drill in: it's almost always one service logging in a loop, or rotation that stopped working. The fix is usually logrotate, not rm — delete the symptom and it refills tomorrow.

A directory shown as > you can't enter. You're not root, so ncdu couldn't measure inside it — its size is underreported. Re-run with sudo ncdu / when you need the true picture of a system filesystem.

Big number on a file you don't recognize, like a core or *.dump. Frequently a crash dump or a database export someone forgot. Confirm with file before deleting — see Gotchas about deleting an active file.

The total at the bottom is far smaller than df says is used. Classic trap: a process is still holding a deleted file open, so the space is gone from df's view but invisible to ncdu (which only sees files that still have names). Hunt it with lsof +L1.

Cheat Sheet

Navigation (the real interface):

↑/↓ move · Enter/→ descend · ← go up · q quit
d delete the selected file/dir (asks first) · n sort by name · s sort by size (default)
a toggle apparent size vs disk usage · g toggle the percentage/graph · ? help · r rescan

Useful invocations:

ncdu / — scan the whole filesystem (add -x to stay on it, skipping mounted filesystems)
ncdu -x / — the server one-liner: don't wander into /proc, /sys, or other mounts
ncdu -o out.json /var — scan now, save results; ncdu -f out.json — browse them later (great over slow SSH)
ncdu --exclude .git /srv — skip noisy paths

How You'll Actually Use It

The pattern is almost always the same. df -h tells you which filesystem is full; then ncdu -x / (or ncdu /var if df pointed at /var) tells you what filled it, interactively, in seconds. On a busy production box you sometimes don't want the live scan competing for disk I/O, so you run ncdu -o /tmp/scan.json -x / once, copy the small JSON to your laptop, and explore it offline with ncdu -f scan.json — same interface, zero further load on the server. For scripted, non-interactive size reports, fall back to plain du; ncdu is for exploring, du is for piping.

Gotchas

d really deletes. It's the one key here with teeth. It confirms first, but there's no undo — and deleting an active log or database file frees nothing until the process closes it, and may corrupt the app. Stop the writer or rotate the file; don't yank it.
Without -x it crosses into other filesystems. Scanning / will descend into /proc, /sys, network mounts, and /mnt drives, inflating numbers and wasting time. Use ncdu -x / to stay on one filesystem.
Run as the right user. Directories you can't read show > and are undercounted. Use sudo for an accurate system-wide scan.
ncdu and df can disagree. ncdu counts files that have names; deleted-but-open files and filesystem reserved blocks don't show up. A big gap usually means a held-open deleted file — check lsof.
The scan is a snapshot. On a fast-growing directory, re-press r to rescan rather than trusting a stale number.

History & Philosophy

ncdu was written by Yoran Heling in 2007 for exactly the situation everyone hits: a remote server with no GUI, a full disk, and du -sh * being too clumsy to explore. It wraps the venerable du idea — sum the bytes under every directory — in an ncurses interface, so the same numbers you could get from du become something you navigate instead of re-running with ever-deeper paths.

And that's the quiet lesson: the data was always there in du, but the interface is the feature. Turning a static report into something you can walk through changed how fast a human can find an answer, without changing the underlying measurement at all. It's a small, perfect example of the Unix habit of building a sharper tool on top of an existing one rather than reinventing it — and the reason a 40 GB log directory that would take minutes to find with du takes ten seconds with ncdu.