NCDU(1)

📦
version 2.11.1 · 7 versions
, in fedora 43, fedora 44, nixpkgs unstable

💖 NCDU 💖 — the NCDU(1) girlie manual

okay so this is NCDU(1), straight outta the General Commands Manual, and bestie it's giving essential. we're gonna walk through every single flag together, no skips, no skimming, periodt. 🦋

✨ NAME ✨

ncdu — NCurses Disk Usage. that's it, that's the name, iconic. 💅

✨ SYNOPSIS ✨

ncdu [-f file] [-o file] [-O file] [-e, --extended, --no-extended]
     [--ignore-config] [-x, --one-file-system, --cross-file-system]
     [--exclude pattern] [-X, --exclude-from file]
     [--include-caches, --exclude-caches]
     [-L, --follow-symlinks, --no-follow-symlinks]
     [--include-kernfs, --exclude-kernfs] [-t, --threads num]
     [-c, --compress, --no-compress] [--compress-level num]
     [--export-block-size num] [-0, -1, -2]
     [-q, --slow-ui-updates, --fast-ui-updates]
     [--enable-shell, --disable-shell]
     [--enable-delete, --disable-delete]
     [--enable-refresh, --disable-refresh] [-r] [--si, --no-si]
     [--disk-usage, --apparent-size] [--show-hidden, --hide-hidden]
     [--show-itemcount, --hide-itemcount] [--show-mtime, --hide-mtime]
     [--show-graph, --hide-graph] [--show-percent, --hide-percent]
     [--graph-style hash | half-block | eighth-block]
     [--shared-column off | shared | unique] [--sort column]
     [--enable-natsort, --disable-natsort]
     [--group-directories-first, --no-group-directories-first]
     [--confirm-quit, --no-confirm-quit]
     [--confirm-delete, --no-confirm-delete] [--delete-command command]
     [--color off | dark | dark-bg] [path]
ncdu [-h, --help]
ncdu [-v, -V, --version]

look at all those options, we're gonna get through all of them, one by one, like the devoted besties we are 🌸

✨ DESCRIPTION ✨

ncdu (that's NCurses Disk Usage, obviously) is an interactive curses-based version of the well-known du(1), and it gives you a fast way to see what directories are eating your disk space. no cap. it's literally the glow-up du deserved. 👑

✨ OPTIONS ✨

🎀 Mode Selection 🎀

  • -h, --help — prints a short lil help message and dips. that's it, that's the whole job. 🫶
  • -v, -V, --version — prints the version and bounces. three whole ways to say "who am i". slay.
  • -f file — loads the given file, which was earlier created with the -o or -O flag. and if file is equivalent to -, the file gets read from standard input — but bestie, listen, reading from standard input is only supported for the JSON format. 💀
and for the sake of preventing a screw-up, the current version of ncdu assumes that the directory information in the imported file does not represent the filesystem on which the file is being imported. which means: the refresh, file deletion and shell spawning options in the browser are all disabled. it's a safety thing, we love a cautious queen. 🎀
  • dir — scans the given directory. the classic. the main character move. 🌟
  • -o file — exports the directory tree in JSON format to file instead of opening the browser interface. if file is -, the data goes to standard output. (peep the examples section further down for some handy use cases, iykyk.) ✨
⚠️ be warned bestie: the exported data can get HUGE when you're exporting a directory with many files. like, 10.000 files will get you an export in the order of 600 to 700 KiB uncompressed, or a little over 100 KiB when compressed with gzip. this scales linearly, so be prepared to handle a few tens of megabytes when you're dealing with millions of files. no one is coming to save you. 😭

consider enabling -c to output Zstandard-compressed JSON — it can significantly reduce the size of the exported data. 💅

and when you're running a multi-threaded scan, or scanning a directory tree that may not fit in memory, consider using -O instead. 🧚

  • -O file — exports the directory tree in binary format to file instead of opening the browser interface. if file is -, the data is written to standard output. the binary format has built-in compression, supports low-memory multi-threaded export (in combination with -t) and can be browsed without importing the entire directory tree into memory. it's giving efficiency, it's giving forethought. 🔥
  • -e, --extended, --no-extended — enable/disable extended information mode. this reads the usual file info plus the ownership, permissions and last modification time for each file. the cost? higher memory usage (by roughly ~30%) and a larger output file when exporting. 💸

when using the file export/import function, this flag should be added both when exporting (so the info actually makes it into the export) and when importing (so it gets read into memory). this flag has no effect when importing a file that was exported without the extended information. 🙈

also: this is what unlocks viewing and sorting by the latest child mtime, or modified time, using m and M, respectively. 💖

  • --ignore-config — do not attempt to load any configuration files. we're going rogue, we're raw-dogging the defaults. 🌈

🔍 Scan Options 🔍

these options affect the scanning progress — they have no effect when importing directory information from a file. noted. 📝

  • -x, --one-file-system — do not cross filesystem boundaries. i.e. only count files and directories on the same filesystem as the directory being scanned. stay in your lane, babe. 💅
  • --cross-file-system — do cross filesystem boundaries. this is the default, but you can specify it to overrule a previously configured -x. sometimes you gotta un-set the vibe. 🔄
  • --exclude pattern — exclude files that match pattern. the files are still displayed by default, but they are not counted towards the disk usage statistics. this argument can be added multiple times to add more patterns. stacking them like accessories. 🎀
  • -X, --exclude-from file — exclude files that match any pattern in file. patterns should be separated by a newline. 📄
  • --include-caches, --exclude-caches — include (that's the default) or exclude directories containing CACHEDIR.TAG. excluded cache directories are still displayed, but their contents will not be scanned or counted towards the disk usage statistics. (https://bford.info/cachedir/) 🗂️
  • -L, --follow-symlinks, --no-follow-symlinks — follow (or not) symlinks and count the size of the file they point to. heads up though: this option does not follow symlinks to directories, and it will cause each symlinked file to count as a unique file. that's different from how hard links are handled. and fr fr, the exact counting behavior of this flag is subject to change in the future. ⚠️
  • --include-kernfs, --exclude-kernfs — (Linux only) include (the default) or exclude Linux pseudo filesystems such as /proc (procfs) and /sys (sysfs). 🐧

the complete list of currently known pseudo filesystems is: binfmt, bpf, cgroup, cgroup2, debug, devpts, proc, pstore, security, selinux, sys, trace.

  • -t, --threads num — number of threads to use when scanning the filesystem. defaults to 1. 🧵

in single-threaded mode, the JSON export (see -o) can operate with very little memory. but in multi-threaded mode the entire directory tree is first constructed in memory and written out after the filesystem scan has completed. this causes a delay in output and requires significantly more memory for large directory trees. 😬 the binary format (see -O) does not have this problem and supports efficient exporting with any number of threads. periodt. 💅

📤 Export Options 📤

these options affect behavior when exporting to file with the -o or -O options.

  • -c, --compress, --no-compress — enable or disable Zstandard compression when exporting to JSON (see -o). ✨
  • --compress-level num — set the Zstandard compression level when using -O or -c. valid values are 1 (fastest) to 19 (slowest). defaults to 4. dial it up if you've got time to burn, bestie. 🔥
  • --export-block-size num — set the block size, in kibibytes, for the binary export format (see -O). larger blocks require more memory but result in better compression efficiency. this option can be combined with a higher --compress-level for even better compression. 👑

accepted values are between 4 and 16000. the default is to start at 64 KiB and then gradually increase the block size for large exports. 🦋

🖥️ Interface Options 🖥️

  • -0 — don't give any feedback while scanning a directory or importing a file, except when a fatal error occurs. ncurses will not be initialized until the scan is complete. and when exporting the data with -o, ncurses will not be initialized at all. this option is the default when exporting to standard output. silent. mysterious. 🤫
  • -1 — write progress information to the terminal, but don't open a full-screen ncurses interface. this option is the default when exporting to a file. 📝
heads up: in some cases, the ncurses browser interface you'll see after the scan/import is complete may look garbled when using this option. if you're not exporting to a file, -2 is usually a better choice. 😭
  • -2 — show a full-screen ncurses interface while scanning a directory or importing a file. this is the only interface that provides feedback on any non-fatal errors while scanning. the full glam experience. 💅
  • -q, --slow-ui-updates, --fast-ui-updates — change the UI update interval while scanning or importing. ncdu updates the screen 10 times a second by default (that's with --fast-ui-updates); this can be decreased to once every 2 seconds with -q or --slow-ui-updates. use this to save bandwidth over remote connections. 🌐 this option has no effect in combination with -0.
  • --enable-shell, --disable-shell — enable or disable shell spawning from the file browser. this feature is enabled by default when scanning a live directory, and disabled when importing from file. 🐚
  • --enable-delete, --disable-delete — enable or disable the built-in file deletion feature. this is enabled by default when scanning a live directory and disabled when importing from file. explicitly disabling the deletion feature can work as a safeguard to prevent accidental data loss. 🛡️
  • --enable-refresh, --disable-refresh — enable or disable directory refreshing from the file browser. enabled by default when scanning a live directory, disabled when importing from file. 🔄
  • -r — read-only mode. when given once, this is an alias for --disable-delete. when given twice it will also add --disable-shell, thus ensuring that there is no way to modify the file system from within ncdu. the ultimate "look but don't touch" setting. 🚫
  • --si, --no-si — list sizes using base 10 prefixes, that is, powers of 1000 (kB, MB, etc), as defined in the International System of Units (SI), instead of the usual base 2 prefixes (KiB, MiB, etc). metric girlies rise. 📏
  • --disk-usage, --apparent-size — pick what you wanna see: disk usage (that's the default bestie, don't stress) or the apparent sizes. You can also flip this live in the file browser with the a key 💅
  • --show-hidden, --hide-hidden — show (default, we love a visible queen) or hide those "hidden" and excluded files. Toggle it in the browser with e ✨
  • --show-itemcount, --hide-itemcount — show or hide (hide is the default, soz) the item counts column. Live toggle in the browser: c 🎀
  • --show-mtime, --hide-mtime — show or hide (again, hide is the default) the last modification time column. Browser toggle is m. Heads up: this one is ignored when you're not in extended mode, so go look at -e 🦋
  • --show-graph, --hide-graph — show (default) or hide the relative size bar column. Toggle it in the browser with g 🌸
  • --show-percent, --hide-percent — show (default) or hide the relative size percent column. Also toggled with g in the browser 💖
  • --graph-style hash | half-block | eighth-block — how should that relative size bar column be drawn, bestie? Recognized values: hash draws ASCII # characters (that's the default and the most portable, periodt), half-block uses half-block drawing characters, and eighth-block uses eighth-block drawing characters. Eighth-block is the most precise but ngl it may not render correctly in all terminals 😭
  • --shared-column off | shared | unique — set it to off to kill the shared size column for directories, shared (the default) to show shared directory sizes as a separate column, or unique to show unique directory sizes as a separate column. You can also cycle through these in the file browser with the u key 🔥
  • --sort column — change the default column we sort on. Accepted values are disk-usage (the default, obvs), name, apparent-size, itemcount or mtime. The last one only makes sense in extended mode, so see -e 👑

You can suffix the column name with -asc or -desc to change the order to ascending or descending, respectively. Like, for example, --sort=name-desc sorts by name in descending order. Slay 💅

  • --enable-natsort, --disable-natsort — enable (default) or disable natural sort when you're sorting by file name 🌈
  • --group-directories-first, --no-group-directories-first — sort (or don't) directories before files 🫶
  • --confirm-quit, --no-confirm-quit — require a confirmation before quitting ncdu. Genuinely helpful when you accidentally press q during or after a very long scan and you have a tiny heart attack 😭
  • --confirm-delete, --no-confirm-delete — require a confirmation before deleting a file or directory. Enabled by default, but you can turn it off if you're absolutely sure you won't accidentally press d 💀
  • --delete-command command — set this to a non-empty string and it replaces the built-in file deletion feature with your own custom shell command ✨

The absolute path of the item to be deleted gets appended to the given command and the whole thing is evaluated in a shell. The command runs from the same directory that ncdu itself was started in. The NCDU_DELETE_PATH environment variable is set to the absolute path of the item to be deleted, and NCDU_LEVEL is set the same way as when you spawn a shell from within ncdu 🐚

After the command finishes, the in-memory view of the selected item is refreshed and directory sizes are adjusted as necessary. It is not a full refresh of the complete directory tree, so if the item has been renamed or moved to another directory, its new location is not automatically picked up. no cap, be aware 🙈

Like, for example, to use rm(1) interactive mode to prompt before each deletion:

ncdu --no-confirm-delete --delete-command 'rm -ri --'

Or to move files to trash:

ncdu --delete-command 'gio trash --'
  • --color off | dark | dark-bg — set the color scheme 🎨 Recognized schemes: off disables colors, dark is a color scheme intended for dark backgrounds, and dark-bg is a variation of the dark color scheme that also works in terminals with a light background.

The default is off.

🌸 CONFIGURATION 🌸

You can configure ncdu by placing command-line options in /etc/ncdu.conf or $HOME/.config/ncdu/config 🫶 If both files exist, the system configuration gets loaded before the user configuration, which lets users override options set in the system configuration. Options given on the command line will override options set in the configuration files. And the files won't be read at all when --ignore-config is given on the command line, so there 💅

The configuration file format is simply one command line option per line. Lines starting with # are ignored. A line can be prefixed with @ to suppress errors while parsing the option. Example configuration file:

# Always enable extended mode
-e

# Disable file deletion
--disable-delete

# Exclude .git directories
--exclude .git

# Read excludes from ~/.ncduexcludes, ignore error if the file does not exist
@--exclude-from ~/.ncduexcludes

✨ KEYS ✨

Okay bestie, here's the whole keyboard vibe check ⌨️💖

  • ? — Open help + keys + about screen 🌸
  • up, down, j, k — Cycle through the items 🦋
  • right, enter, l — Open selected directory 👑
  • left, <, h — Go to parent directory ⬆️
  • n — Order by filename (press again for descending order) 🔤
  • s — Order by filesize (press again for descending order) 📦
  • C — Order by number of items (press again for descending order) 🔢
  • a — Toggle between showing disk usage and showing apparent size 💅
  • M — Order by latest child mtime, or modified time (press again for descending order). Requires the -e flag ⏰
  • d — Delete the selected file or directory. An error message will be shown when the contents of the directory do not match or do not exist anymore on the filesystem 💀
  • t — Toggle dirs before files when sorting 🎀
  • g — Toggle between showing percentage, graph, both, or none. Percentage is relative to the size of the current directory, graph is relative to the largest item in the current directory 📊
  • u — Toggle display of the shared / unique size column for directories that share hard links. This column is only visible if the current listing contains directories with shared hard links 🔗
  • c — Toggle display of child item counts 🧮
  • m — Toggle display of latest child mtime, or modified time. Requires the -e flag ⏱️
  • e — Show/hide 'hidden' or 'excluded' files and directories. Be aware that even if you can't see the hidden files and directories, they are still there and they are still included in the directory sizes. If you suspect that the totals shown at the bottom of the screen are not correct, make sure you haven't enabled this option 👀
  • i — Show information about the current selected item ℹ️
  • r — Refresh/recalculate the current directory 🔄
  • b — Spawn shell in current directory 🐚

ncdu determines your preferred shell from the NCDU_SHELL or SHELL environment variable (in that order), or calls /bin/sh if neither are set. This lets you also configure another command to be run when the b key is pressed. For example, to spawn the vifm(1) file manager instead of a shell, run ncdu as follows:

NCDU_SHELL=vifm ncdu

The NCDU_LEVEL environment variable is set or incremented before spawning the shell, allowing you to detect if your shell is running from within ncdu. This can be useful to avoid nesting multiple instances, although ncdu itself does not (currently) warn about or prevent this situation 🌀

  • q — Quit ✌️

🎀 FILE FLAGS 🎀

Entries in the browser interface may be prefixed by a one-character flag. These flags have the following meaning, bestie — learn them and you'll read the screen like a main character 👑

  • ! — An error occurred while reading this directory 😭
  • . — An error occurred while reading a subdirectory, so the indicated size may not be correct 🙈
  • < — File or directory is excluded from the statistics by using exclude patterns 🚫
  • > — Directory is on another filesystem 🗂️
  • ^ — Directory is excluded from the statistics due to being a Linux pseudo filesystem 🐧
  • @ — This is neither a file nor a folder (symlink, socket, ...) ✨
  • H — Same file was already counted (hard link) 🔗
  • e — Empty directory 🫙

💖 EXAMPLES 💖

To scan and browse the directory you're currently in, all you need is a simple:

ncdu

To scan a full filesystem, for example your root filesystem, you'll want to use -x:

ncdu -x /

Since scanning a large directory may take a while, you can scan a directory and export the results for later viewing:

ncdu -1xO export.ncdu /
# ...some time later:
ncdu -f export.ncdu

To export from a cron job, make sure to replace -1 with -0 to suppress unnecessary progress output 🤫

You can also export a directory and browse it once scanning is done:

ncdu -co- | tee export.json.zst | ./ncdu -f-

To scan a system remotely, but browse through the files locally:

ssh user@system ncdu -co- / | ./ncdu -f-

Remote scanning and local viewing has two major advantages when compared to running ncdu directly on the remote system: You can browse through the scanned directory on the local system without any network latency, and ncdu does not keep the entire directory structure in memory when exporting, so this won't consume much memory on the remote system. iconic behaviour honestly 🔥

🌈 SEE ALSO 🌈

💜 AUTHORS 💜

Written by Yorhel <projects@yorhel.nl>

💀 BUGS (the tea on what's lowkey broken)

ok bestie, gather round, because we gotta be honest about the ✨imperfections✨. Nothing catastrophic, but you deserve to know fr fr.

  • Directory hard links and firmlinks (MacOS) are not supported. They don't get detected as hard links, so they just get scanned and counted multiple times. It's giving "double dipping at the snack table" 🍓🙈.
  • Some minor glitches may appear when displaying filenames that contain multibyte or multicolumn characters. Aesthetic only, no cap — your files are fine, the display is just doing a lil dance 💅.
  • The unique and shared directory sizes are calculated based on the assumption that the link count of hard links does not change during a filesystem scan or in between refreshes. If that does happen — like when a hard link gets deleted — then those numbers will be very much incorrect 😭 and you'll need a full refresh by restarting ncdu to get correct numbers again. No shortcuts, bestie, just restart it 🫶.
  • All sizes are internally represented as a signed 64bit integer. So if you somehow have a directory larger than 8 EiB minus one byte, ncdu will clip its size to 8 EiB minus one byte. And when you're deleting or refreshing items in a directory with a clipped size, the resulting sizes will be incorrect. Likewise, item counts are stored in a 32-bit integer, so they'll be incorrect in the unlikely event that you happen to have more than 4 billion items in a directory. Like… if you're hitting that, honestly iconic, but also please go outside 🌸.
Please report any other bugs you may find at the bug tracker, which can be found on the web site at https://github.com/BratishkaErik/ncdu/issues. Do it for the girlies 🎀. Actual bugs get fixed, and that's the real main character energy 👑.

and that's the whole page, bestie!! 💖 this one shipped with the Debian version, dated July 11, 2026, for the one and only NCDU(1) 🦋. now go scan some disks and slay ✨👑💜

📦 where this page comes from