dust README

The project's README from github.com/bootandy/dust. As one markdown file: README.md.

Dust

du + rust = dust. Like du but more intuitive.

Why

Because I want an easy way to see where my disk is being used.

Demo

dust demo — interactive disk usage analysis

Study the above demo

We cd into a webapp it is 72K in size.
We see 32K in the src folder. Note the bar jumps to 44%. Half of the webapp is in src
We see 8K in the src/utils. The bar jumps down to 11% but a shadow stays at 44% showing that it is part of the src folder
We then demo the -d 2 flag - Show a depth of 2 folders
We demo the -n 5 flag - Show only 5 items (by default we show terminal height items)

Install

Quick Install (Linux, macOS, Windows)

curl -sSfL https://raw.githubusercontent.com/bootandy/dust/refs/heads/master/install.sh | sh

Cargo

Cargo

cargo install du-dust

🍺 Homebrew (Mac OS)

brew install dust

🍺 Homebrew (Linux)

brew install dust

DNF (Fedora Linux)

sudo dnf install du-dust

Snap Ubuntu and supported systems

snap install dust

Note: dust installed through snap can only access files stored in the /home directory. See danie-dejager/dust-snap#2 for more information.

mise

mise use -g dust

Pacstall (Debian/Ubuntu)

pacstall -I dust-bin

Anaconda (conda-forge)

conda install -c conda-forge dust

deb-get (Debian/Ubuntu)

deb-get install du-dust

x-cmd

x env use dust

Windows:

scoop install dust
Windows GNU version - works
Windows MSVC - requires: VCRUNTIME140.dll

Download

Download Linux/Mac binary from Releases
unzip file: tar -xvf _downloaded_file.tar.gz
move file to executable path: sudo mv dust /usr/local/bin/

Overview

Dust is meant to give you an instant overview of which directories are using disk space without requiring sort or head. Dust will print a maximum of one 'Did not have permissions message'.

Dust will list a slightly-less-than-the-terminal-height number of the biggest subdirectories or files and will smartly recurse down the tree to find the larger ones. There is no need for a '-d' flag or a '-h' flag. The largest subdirectories will be colored.

The different colors on the bars: These represent the combined tree hierarchy & disk usage. The shades of grey are used to indicate which parent folder a subfolder belongs to. For instance, look at the above screenshot. .steam is a folder taking 44% of the space. From the .steam bar is a light grey line that goes up. All these folders are inside .steam so if you delete .steam all that stuff will be gone too.

If you are new to the tool I recommend to try tweaking the -n parameter. dust -n 10, dust -n 50.

Usage

Usage: dust
Usage: dust <dir>
Usage: dust <dir>  <another_dir> <and_more>
Usage: dust -p (full-path - Show fullpath of the subdirectories)
Usage: dust -s (apparent-size - shows the length of the file as opposed to the amount of disk space it uses)
Usage: dust -n 30  (Shows 30 directories instead of the default [default is terminal height])
Usage: dust -d 3  (Shows 3 levels of subdirectories)
Usage: dust -D (Show only directories (eg dust -D))
Usage: dust -F (Show only files - finds your largest files)
Usage: dust -r (reverse order of output)
Usage: dust -o si/b/kb/kib/mb/mib/gb/gib (si - prints sizes in powers of 1000. Others print size in that format).
Usage: dust -X ignore  (ignore all files and directories with the name 'ignore')
Usage: dust -x (Only show directories on the same filesystem)
Usage: dust -b (Do not show percentages or draw ASCII bars)
Usage: dust -B (--bars-on-right - Percent bars moved to right side of screen)
Usage: dust -i (Do not show hidden files)
Usage: dust -c (No colors [monochrome])
Usage: dust -C (Force colors)
Usage: dust --dim (Dim the percent bars to reduce brightness on dark terminals)
Usage: dust -f (Count files instead of diskspace [Counts by inode, to include duplicate inodes use dust -f -s])
Usage: dust -t (Group by filetype)
Usage: dust -z 10M (min-size, Only include files larger than 10M)
Usage: dust -e regex (Only include files matching this regex (eg dust -e "\.png$" would match png files))
Usage: dust -v regex (Exclude files matching this regex (eg dust -v "\.png$" would ignore png files))
Usage: dust -L (dereference-links - Treat sym links as directories and go into them)
Usage: dust -P (Disable the progress indicator)
Usage: dust -T (Set the number of walker threads. Default is the CPU count. For high-latency storage like NFS or remote mounts, a higher count can speed up the walk by overlapping more concurrent stat calls.)
Usage: dust -R (For screen readers. Removes bars/symbols. Adds new column: depth level. (May want to use -p for full path too))
Usage: dust --skip-total (No total row will be displayed)
Usage: dust -z 40000/30MB/20kib (Exclude output files/directories below size 40000 bytes / 30MB / 20KiB)
Usage: dust -j (Prints JSON representation of directories, try: dust -j  | jq)
Usage: dust --files0-from=FILE (Read NUL-terminated file paths from FILE; if FILE is '-', read from stdin)
Usage: dust --files-from=FILE (Read newline-terminated file paths from FILE; if FILE is '-', read from stdin)
Usage: dust --collapse=node-modules will keep the node-modules folder collapsed in display instead of recursively opening it
Usage: dust --dim Displays dimmer bars

Config file

Dust has a config file where the above options can be set. Either: $XDG_CONFIG_HOME/dust/config.toml (falling back to ~/.config/dust/config.toml) or ~/.dust.toml

$ cat ~/.config/dust/config.toml
reverse=true
limit-filesystem=true

Keys use the long flag name in kebab-case. See config/config.toml for a fuller sample.

Alternatives

NCDU
dutree
dua
pdu
dirstat-rs
du -d 1 -h | sort -h

Why to use Dust over the Alternatives

Dust simply Does The Right Thing when handling lots of small files & directories. Dust keeps the output simple by only showing large entries.

Tools like ncdu & baobab, give you a view of directory sizes but you have no idea where the largest files are. For example directory A could have a size larger than directory B, but in fact the largest file is in B and not A. Finding this out via these other tools is not trivial whereas Dust will show the large file clearly in the tree hierarchy

Dust will not count hard links multiple times (unless you want to -s).

Typing dust -n 90 will show you your 90 largest entries. -n is not quite like head -n or tail -n, dust is intelligent and chooses the largest entries

Searching Database…

12.5K ·GitHub

What is this?

Dust is a more intuitive replacement for the 'du' command, written in Rust, that shows which directories and files are eating your disk space.

Is it a GUI tool or a command-line tool?

It is a command-line tool only; there is no GUI, just a colored tree printed in the terminal.

Do I need Rust installed to use it?

No, you only need Rust/Cargo if installing via 'cargo install'; otherwise prebuilt binaries and package managers (Homebrew, Snap, Pacstall, deb-get, Scoop) work without it.

Any install pitfalls on Windows?

On Windows the GNU build works fine via Scoop, but the MSVC build requires the VCRUNTIME140.dll to be present.

Does it run on Linux, macOS and Windows?

Yes, it supports Linux, macOS and Windows with installers and binaries for all three.

How is dust different from ncdu or baobab?

Unlike ncdu or baobab, dust shows the largest individual file within a directory tree directly in the output, not just directory-level totals, so you instantly see where the big files actually are.

How does dust decide how many entries to show?

By default it shows roughly as many entries as fit your terminal height, but you can control this with -n (e.g. 'dust -n 10') or limit recursion depth with -d.

Does dust double-count hard links?

No, by default dust does not count hard links multiple times; you can force counting them separately with the -s flag.

Can I customize dust's default behavior?

Yes, you can set default flags permanently in a config.toml file at ~/.config/dust/config.toml or ~/.dust.toml using kebab-case flag names.

What are similar projects?

veet, hexyl, ripgrep, bottom, applesauce, eza, spotify-tui, fd

Which topics is it in?

disk-usage, homebrew, sysadmin, cli-tool, command-line, utility, performance, rust, command-line-tool, terminal, tool, apache-2.0

Creator: bootandy
Size: 1.4 MB
Stars: 12.5K
Updated: CommitSep 16 Releasev1.2.6Sep 16
Age: 8y
Commits · 90 Days