1NCDU(1)                           ncdu manual                          NCDU(1)
2
3
4

NAME

6       ncdu - NCurses Disk Usage
7

SYNOPSIS

9       ncdu [options] dir
10

DESCRIPTION

12       ncdu (NCurses Disk Usage) is a curses-based version of the well-known
13       'du', and provides a fast way to see what directories are using your
14       disk space.
15

OPTIONS

17   Mode Selection
18       -h, --help
19           Print a short help message and quit.
20
21       -v, -V, --version
22           Print ncdu version and quit.
23
24       -f FILE
25           Load the given file, which has earlier been created with the "-o"
26           option. If FILE is equivalent to "-", the file is read from
27           standard input.
28
29           For the sake of preventing a screw-up, the current version of ncdu
30           will assume that the directory information in the imported file
31           does not represent the filesystem on which the file is being
32           imported. That is, the refresh, file deletion and shell spawning
33           options in the browser will be disabled.
34
35       dir Scan the given directory.
36
37       -o FILE
38           Export all necessary information to FILE instead of opening the
39           browser interface. If FILE is "-", the data is written to standard
40           output.  See the examples section below for some handy use cases.
41
42           Be warned that the exported data may grow quite large when
43           exporting a directory with many files. 10.000 files will get you an
44           export in the order of 600 to 700 KiB uncompressed, or a little
45           over 100 KiB when compressed with gzip. This scales linearly, so be
46           prepared to handle a few tens of megabytes when dealing with
47           millions of files.
48
49       -e  Enable extended information mode. This will, in addition to the
50           usual file information, also read the ownership, permissions and
51           last modification time for each file. This will result in higher
52           memory usage (by roughly ~30%) and in a larger output file when
53           exporting.
54
55           When using the file export/import function, this flag will need to
56           be added both when exporting (to make sure the information is added
57           to the export), and when importing (to read this extra information
58           in memory). This flag has no effect when importing a file that has
59           been exported without the extended information.
60
61           This enables viewing and sorting by the latest child mtime, or
62           modified time, using 'm' and 'M', respectively.
63
64   Interface options
65       -0  Don't give any feedback while scanning a directory or importing a
66           file, other than when a fatal error occurs. Ncurses will not be
67           initialized until the scan is complete. When exporting the data
68           with "-o", ncurses will not be initialized at all. This option is
69           the default when exporting to standard output.
70
71       -1  Similar to "-0", but does give feedback on the scanning progress
72           with a single line of output. This option is the default when
73           exporting to a file.
74
75           In some cases, the ncurses browser interface which you'll see after
76           the scan/import is complete may look garbled when using this
77           option. If you're not exporting to a file, "-2" is probably a
78           better choice.
79
80       -2  Provide a full-screen ncurses interface while scanning a directory
81           or importing a file. This is the only interface that provides
82           feedback on any non-fatal errors while scanning.
83
84       -q  Quiet mode. While scanning or importing the directory, ncdu will
85           update the screen 10 times a second by default, this will be
86           decreased to once every 2 seconds in quiet mode. Use this feature
87           to save bandwidth over remote connections. This option has no
88           effect when "-0" is used.
89
90       -r  Read-only mode. This will disable the built-in file deletion
91           feature. This option has no effect when "-o" is used, because there
92           will not be a browser interface in that case. It has no effect when
93           "-f" is used, either, because the deletion feature is disabled in
94           that case anyway.
95
96           WARNING: This option will only prevent deletion through the file
97           browser. It is still possible to spawn a shell from ncdu and delete
98           or modify files from there. To disable that feature as well, pass
99           the "-r" option twice (see "-rr").
100
101       -rr In addition to "-r", this will also disable the shell spawning
102           feature of the file browser.
103
104       --si
105           List sizes using base 10 prefixes, that is, powers of 1000 (KB, MB,
106           etc), as defined in the International System of Units (SI), instead
107           of the usual base 2 prefixes, that is, powers of 1024 (KiB, MiB,
108           etc).
109
110       --confirm-quit
111           Requires a confirmation before quitting ncdu. Very helpful when you
112           accidentally press 'q' during or after a very long scan.
113
114       --color SCHEME
115           Select a color scheme. Currently only two schemes are recognized:
116           off to disable colors (the default) and dark for a color scheme
117           intended for dark backgrounds.
118
119   Scan Options
120       These options affect the scanning progress, and have no effect when
121       importing directory information from a file.
122
123       -x  Do not cross filesystem boundaries, i.e. only count files and
124           directories on the same filesystem as the directory being scanned.
125
126       --exclude PATTERN
127           Exclude files that match PATTERN. The files will still be displayed
128           by default, but are not counted towards the disk usage statistics.
129           This argument can be added multiple times to add more patterns.
130
131       -X FILE, --exclude-from FILE
132           Exclude files that match any pattern in FILE. Patterns should be
133           separated by a newline.
134
135       --exclude-caches
136           Exclude directories containing CACHEDIR.TAG.  The directories will
137           still be displayed, but not their content, and they are not counted
138           towards the disk usage statistics.  See
139           http://www.brynosaurus.com/cachedir/
140
141       -L, --follow-symlinks
142           Follow symlinks and count the size of the file they point to. As of
143           ncdu 1.14, this option will not follow symlinks to directories and
144           will count each symlinked file as a unique file (i.e. unlike how
145           hard links are handled). This is subject to change in later
146           versions.
147
148       --exclude-firmlinks
149           (MacOS only) Exclude firmlinks.
150
151       --exclude-kernfs
152           (Linux only) Exclude Linux pseudo filesystems, e.g. /proc (procfs),
153           /sys (sysfs).
154
155           The complete list of currently known pseudo filesystems is: binfmt,
156           bpf, cgroup, cgroup2, debug, devpts, proc, pstore, security,
157           selinux, sys, trace.
158

KEYS

160       ?   Show help + keys + about screen
161
162       up, down j, k
163           Cycle through the items
164
165       right, enter, l
166           Open selected directory
167
168       left, <, h
169           Go to parent directory
170
171       n   Order by filename (press again for descending order)
172
173       s   Order by filesize (press again for descending order)
174
175       C   Order by number of items (press again for descending order)
176
177       a   Toggle between showing disk usage and showing apparent size.
178
179       M   Order by latest child mtime, or modified time. (press again for
180           descending order) Requires the -e flag.
181
182       d   Delete the selected file or directory. An error message will be
183           shown when the contents of the directory do not match or do not
184           exist anymore on the filesystem.
185
186       t   Toggle dirs before files when sorting.
187
188       g   Toggle between showing percentage, graph, both, or none. Percentage
189           is relative to the size of the current directory, graph is relative
190           to the largest item in the current directory.
191
192       c   Toggle display of child item counts.
193
194       m   Toggle display of latest child mtime, or modified time. Requires
195           the -e flag.
196
197       e   Show/hide 'hidden' or 'excluded' files and directories. Please note
198           that even though you can't see the hidden files and directories,
199           they are still there and they are still included in the directory
200           sizes. If you suspect that the totals shown at the bottom of the
201           screen are not correct, make sure you haven't enabled this option.
202
203       i   Show information about the current selected item.
204
205       r   Refresh/recalculate the current directory.
206
207       b   Spawn shell in current directory.
208
209           Ncdu will determine your preferred shell from the "NCDU_SHELL" or
210           "SHELL" variable (in that order), or will call "/bin/sh" if neither
211           are set.  This allows you to also configure another command to be
212           run when he 'b' key is pressed. For example, to spawn the vifm(1)
213           file manager instead of a shell, run ncdu as follows:
214
215             export NCDU_SHELL=vifm
216             ncdu
217
218       q   Quit
219

FILE FLAGS

221       Entries in the browser interface may be prefixed by a one-character
222       flag. These flags have the following meaning:
223
224       !   An error occurred while reading this directory.
225
226       .   An error occurred while reading a subdirectory, so the indicated
227           size may not be correct.
228
229       <   File or directory is excluded from the statistics by using exclude
230           patterns.
231
232       >   Directory is on another filesystem.
233
234       ^   Directory is excluded from the statistics due to being a Linux
235           pseudo filesystem.
236
237       @   This is neither a file nor a folder (symlink, socket, ...).
238
239       H   Same file was already counted (hard link).
240
241       e   Empty directory.
242

EXAMPLES

244       To scan and browse the directory you're currently in, all you need is a
245       simple:
246
247         ncdu
248
249       If you want to scan a full filesystem, your root filesystem, for
250       example, then you'll want to use "-x":
251
252         ncdu -x /
253
254       Since scanning a large directory may take a while, you can scan a
255       directory and export the results for later viewing:
256
257         ncdu -1xo- / | gzip >export.gz
258         # ...some time later:
259         zcat export.gz | ncdu -f-
260
261       To export from a cron job, make sure to replace "-1" with "-0" to
262       suppress any unnecessary output.
263
264       You can also export a directory and browse it once scanning is done:
265
266         ncdu -o- | tee export.file | ./ncdu -f-
267
268       The same is possible with gzip compression, but is a bit kludgey:
269
270         ncdu -o- | gzip | tee export.gz | gunzip | ./ncdu -f-
271
272       To scan a system remotely, but browse through the files locally:
273
274         ssh -C user@system ncdu -o- / | ./ncdu -f-
275
276       The "-C" option to ssh enables compression, which will be very useful
277       over slow links. Remote scanning and local viewing has two major
278       advantages when compared to running ncdu directly on the remote system:
279       You can browse through the scanned directory on the local system
280       without any network latency, and ncdu does not keep the entire
281       directory structure in memory when exporting, so you won't consume much
282       memory on the remote system.
283
285       Every disk usage analysis utility has its own way of (not) counting
286       hard links.  There does not seem to be any universally agreed method of
287       handling hard links, and it is even inconsistent among different
288       versions of ncdu. This section explains what each version of ncdu does.
289
290       ncdu 1.5 and below does not support any hard link detection at all:
291       each link is considered a separate inode and its size is counted for
292       every link. This means that the displayed directory sizes are incorrect
293       when analyzing directories which contain hard links.
294
295       ncdu 1.6 has basic hard link detection: When a link to a previously
296       encountered inode is detected, the link is considered to have a file
297       size of zero bytes.  Its size is not counted again, and the link is
298       indicated in the browser interface with a 'H' mark. The displayed
299       directory sizes are only correct when all links to an inode reside
300       within that directory. When this is not the case, the sizes may or may
301       not be correct, depending on which links were considered as "duplicate"
302       and which as "original". The indicated size of the topmost directory
303       (that is, the one specified on the command line upon starting ncdu) is
304       always correct.
305
306       ncdu 1.7 and later has improved hard link detection. Each file that has
307       more than two links has the "H" mark visible in the browser interface.
308       Each hard link is counted exactly once for every directory it appears
309       in. The indicated size of each directory is therefore, correctly, the
310       sum of the sizes of all unique inodes that can be found in that
311       directory. Note, however, that this may not always be same as the space
312       that will be reclaimed after deleting the directory, as some inodes may
313       still be accessible from hard links outside it.
314

BUGS

316       Directory hard links are not supported. They will not be detected as
317       being hard links, and will thus be scanned and counted multiple times.
318
319       Some minor glitches may appear when displaying filenames that contain
320       multibyte or multicolumn characters.
321
322       All sizes are internally represented as a signed 64bit integer. If you
323       have a directory larger than 8 EiB minus one byte, ncdu will clip its
324       size to 8 EiB minus one byte. When deleting items in a directory with a
325       clipped size, the resulting sizes will be incorrect.
326
327       Item counts are stored in a signed 32-bit integer without overflow
328       detection.  If you have a directory with more than 2 billion files,
329       quite literally anything can happen.
330
331       On macOS 10.15 and later, running ncdu on the root directory without
332       `--exclude-firmlinks` may cause directories to be scanned and counted
333       multiple times. Firmlink cycles are currently (1.15.1) not detected, so
334       it may also cause ncdu to get stuck in an infinite loop and eventually
335       run out of memory.
336
337       Please report any other bugs you may find at the bug tracker, which can
338       be found on the web site at https://dev.yorhel.nl/ncdu
339

AUTHOR

341       Written by Yoran Heling <projects@yorhel.nl>.
342

SEE ALSO

344       du(1)
345
346
347
348ncdu-1.15                         2020-06-07                           NCDU(1)
Impressum