Looking at Linux disk usage with the ncdu command

The ncdu command provides a useful and convenient way to view disk usage. The name stands for “NCurses disk usage”. This means that it’s based on ncurses which, like curses, is a terminal control library used on Unix/Linux systems. The curses part of each name is a pun on “cursor” or “cursor optimization” and is unrelated to the use of foul language.

You can think of ncdu as a disk usage analyzer with an ncurses interface. It can be especially useful when looking for disk-space hogs on a remote server for which you don’t have access to a graphical interface.

To use ncdu, you can just type “ncdu”, but what you will see depends on where you have positioned yourself in the file system as it reports the space used by files and directories in that location.

$ ncdu
ncdu 1.14.1 ~ Use the arrow keys to navigate, press ? for help
--- /home/shs ------------------------------------------------------------------
    1.2 GiB [##########] /.cache
  242.9 MiB [##        ] /Downloads
  204.5 MiB [#         ] /Desktop
  130.4 MiB [#         ]  XPS 8900-desktop_service-manual.pdf
   77.0 MiB [          ] /.mozilla
   22.3 MiB [          ]  LinuxWords.pdf
   12.6 MiB [          ] /myfonts
    7.2 MiB [          ]  XPS 8900 Desktop Specs.pdf
    6.2 MiB [          ] /Documents
    4.3 MiB [          ] /.config
    3.8 MiB [          ]  typescript
    3.3 MiB [          ] /bin
    2.0 MiB [          ] /Pictures
    1.8 MiB [          ] /.local
  824.0 KiB [          ] /.GlobalProtect
  356.0 KiB [          ]  LinuxWorks-2.pdf
  332.0 KiB [          ]  pavers.png
  196.0 KiB [          ] /YardSale
  120.0 KiB [          ]  paver.jpg
  112.0 KiB [          ] /.cinnamon
   32.0 KiB [          ] /IDG

You can use your up and down arrow keys to move through the displayed files and directories. In fact, if you press the enter key on a listed directory, you’ll move into that directory and be able to view its contents. Then tap on the left arrow key to return to the prior directory.

Notice that the files and directories are listed in size order with the largest shown first. In the output above, the .cache file is the largest at 1.2GB. To exit, simply press q.

It takes a while for the tool to provide data, especially if you ask it to look at large directories. If you begin at the root directory, for example, the tool will have many more files to examine. When you first start ncdu, you will see something like the following as it runs through the contents of the current directory and looks at each file.

   lqqqScanning...qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqk
   x                                                                         x
   x Total items: 148091   size:   6.7 GiB                                   x
   x Current item: /ubuntu/usr/src/linux-hea...-18/fs/notify/dnotify/Kconfig x
   x                                                                         x
   x Warning: error scanning /ubuntu/etc/sssd                                x
   x  some directory sizes may not be correct                                x
   x                                                                         x
   x          ...                                           Press q to abort x
   mqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqj

After a while, it will return your report.

    7.1 GiB [######    ] /usr
.   1.9 GiB [#         ] /home
    1.5 GiB [#         ] /media
.   1.0 GiB [          ] /var
. 405.8 MiB [          ] /boot
   28.3 MiB [          ] /opt
.  16.7 MiB [          ] /etc
.   3.3 MiB [          ] /tmp
.   1.6 MiB [          ] /run
   16.0 KiB [          ] /dev
!  16.0 KiB [          ] /lost+found

A help page is available for ncdu as well as a man page.

shs@firefly:/$ ncdu --help
ncdu  

  -h,--help                  This help message
  -q                         Quiet mode, refresh interval 2 seconds
  -v,-V,--version            Print version
  -x                         Same filesystem
  -e                         Enable extended information
  -r                         Read only
  -o FILE                    Export scanned directory to FILE
  -f FILE                    Import scanned directory from FILE
  -0,-1,-2                   UI to use when scanning (0=none,2=full ncurses)
  --si                       Use base 10 (SI) prefixes instead of base 2
  --exclude PATTERN          Exclude files that match PATTERN
  -X, --exclude-from FILE    Exclude files that match any pattern in FILE
  -L, --follow-symlinks      Follow symbolic links (excluding directories)
  --exclude-caches           Exclude directories containing CACHEDIR.TAG
  --confirm-quit             Confirm quitting ncdu
  --color SCHEME             Set color scheme

Note that the -o option doesn’t prepare a report. Instead, it saves all of the that it collects on each file. For example, you might run a command like this:

$ ncdu -o /tmp/dureport

When it’s done, your output file will look like this:

$ head -11 /tmp/dureport
[1,1,{"progname":"ncdu","progver":"1.14.1","timestamp":1639414007},
[{"name":"/home/shs","asize":4096,"dsize":4096,"dev":2067,"ino":39845890},
[{"name":"Pictures","asize":4096,"dsize":4096,"ino":39845933},
{"name":"shs@192.168.0.11","asize":412675,"dsize":413696,"ino":39849638},
{"name":"Screenshot from 2021-07-07 10-19
43.png","asize":80972,"dsize":81920,"ino":39851217},
{"name":"MintDesktop2.png","asize":333930,"dsize":335872,"ino":39849646},
{"name":"Screenshot from 2021-05-12 15-31-40.png","asize":304458,"dsize":307200,"ino":39845894},
{"name":"MintDesktop.png","asize":412675,"dsize":413696,"ino":39846106},
{"name":"Screenshot from 2021-07-07 10-16-54.png","asize":254307,"dsize":258048,"ino":39851211},
{"name":"font-manager.png","asize":253149,"dsize":253952,"ino":39847669}],
[{"name":".cache","asize":4096,"dsize":4096,"ino":39845908},

While the output of the ncdu command shows you how used disk space is occupied and what files are using the most disk space, it won’t tell you how much space remains available. Balance its output with the df -h command to put disk usage data back into perspective.

$ df -h
Filesystem      Size  Used Avail Use% Mounted on
udev            1.7G     0  1.7G   0% /dev
tmpfs           340M  1.7M  339M   1% /run
/dev/sdb3       903G   19G  838G   3% /
tmpfs           1.7G   16K  1.7G   1% /dev/shm
tmpfs           5.0M  4.0K  5.0M   1% /run/lock
tmpfs           1.7G     0  1.7G   0% /sys/fs/cgroup
/dev/sdb1       511M  5.3M  506M   2% /boot/efi
/dev/sdb2       930G   12G  871G   2% /ubuntu
tmpfs           340M   24K  340M   1% /run/user/100

Wrap-Up

The ncdu command works quickly and provides useful data on disk-space usage. If your file system is filling up, it’s very helpful in determining how that disk space is being used.