go DiskUsage()
Pretty fast disk usage analyzer written in Go.
Gdu is intended primarily for SSD disks where it can fully utilize parallel processing.
However HDDs work as well, but the performance gain is not so huge.
Installation
Head for the releases page and download the binary for your system.
Using curl:
curl -L https://github.com/dundee/gdu/releases/latest/download/gdu_linux_amd64.tgz | tar xz
chmod +x gdu_linux_amd64
mv gdu_linux_amd64 /usr/bin/gdu
See the installation page for other ways how to install Gdu to your system.
Or you can use Gdu directly via Docker:
docker run --rm --init --interactive --tty --privileged --volume /:/mnt/root ghcr.io/dundee/gdu /mnt/root
Usage
gdu [flags] [directory_to_scan...]
Flags:
--archive-browsing Enable browsing of zip/jar/tar archives (tar, tar.gz, tar.bz2, tar.xz)
--collapse-path Collapse single-child directory chains
--config-file string Read config from file (default is $HOME/.gdu.yaml)
--ctrl-c-quits Quit gdu when Ctrl+C is pressed during a scan instead of stopping the scan and keeping results (Esc always stops the scan)
-D, --db string Store analysis in database (*.sqlite for SQLite, *.badger for BadgerDB)
--depth int Show directory structure up to specified depth in non-interactive mode (0 means the flag is ignored); also limits entries inside browsed archives
--enable-profiling Enable collection of profiling data and provide it on http://localhost:6060/debug/pprof/
-E, --exclude-type strings File types to exclude (e.g., --exclude-type yaml,json)
--exclusive-size Linux only: report file usage as the bytes not shared with other files (reflinks), i.e. what deleting them frees
-L, --follow-symlinks Follow symlinks for files, i.e. show the size of the file to which symlink points to (symlinks to directories are not followed)
-h, --help help for gdu
-i, --ignore-dirs strings Paths to ignore (separated by comma). Can be absolute or relative to current directory (default [/proc,/dev,/sys,/run])
-I, --ignore-dirs-pattern strings Path patterns to ignore (separated by comma)
-X, --ignore-from string Read path patterns to ignore from file
-G, --ignore-from-gitignore string Read directories to ignore from file with .gitignore-style patterns
-f, --input-file string Import analysis from JSON file
--interactive Force interactive mode even when output is not a TTY
-l, --log-file string Path to a logfile (default "/dev/null")
--max-age string Include files with mtime no older than DURATION (e.g., 7d, 2h30m, 1y2mo)
-m, --max-cores int Set max cores that Gdu will use. 8 cores available (default 8)
--min-age string Include files with mtime at least DURATION old (e.g., 30d, 1w)
--mouse Use mouse
-c, --no-color Do not use colorized output
--no-confirm-quit Do not ask for confirmation before quitting after a long scan
-x, --no-cross Do not cross filesystem boundaries
--no-delete Do not allow deletions
-H, --no-hidden Ignore hidden directories (beginning with dot)
--no-prefix Show sizes as raw numbers without any prefixes (SI or binary) in non-interactive mode
-p, --no-progress Do not show progress in non-interactive mode
--no-spawn-shell Do not allow spawning shell
-u, --no-unicode Do not use Unicode symbols (for size bar)
--no-view-file Do not allow viewing file contents
-n, --non-interactive Do not run in interactive mode
--output-attrs string Export only selected JSON attributes (name,asize,dsize,shsize,items,mtime,notreg,ino)
-o, --output-file string Export all info into file as JSON
-r, --read-from-storage Use existing database instead of re-scanning
--reverse-sort Reverse the sorting order in non-interactive mode (smallest to largest by default)
--sequential Use sequential scanning (intended for rotating HDDs)
--shell string Set the shell spawned with the b key
-A, --show-annexed-size Use apparent size of git-annex'ed files in case files are not present locally (real usage is zero)
-a, --show-apparent-size Show apparent size
-d, --show-disks Show all mounted disks
-k, --show-in-kib Show sizes in KiB (or kB with --si) in non-interactive mode
-C, --show-item-count Show number of items in directory
-M, --show-mtime Show latest mtime of items in directory
-B, --show-relative-size Show relative size
--show-symlink-target Show symlink target (name -> target) in the file list
--si Show sizes with decimal SI prefixes (kB, MB, GB) instead of binary prefixes (KiB, MiB, GiB)
--since string Include files with mtime >= WHEN. WHEN accepts RFC3339 timestamp (e.g., 2025-08-11T01:00:00-07:00) or date only YYYY-MM-DD (calendar-day compare; includes the whole day)
-s, --summarize Show only a total in non-interactive mode
-t, --top int Show only top X largest files in non-interactive mode
--trash-command string Command used to move items to trash instead of the built-in trash (e.g. 'trash-put --trash-dir ~/mytrash')
-T, --type strings File types to include (e.g., --type yaml,json)
--until string Include files with mtime <= WHEN. WHEN accepts RFC3339 timestamp or date only YYYY-MM-DD
-v, --version Print version
--web Run the web UI (serves a browser interface instead of the terminal UI)
--web-listen string Address for the web UI to listen on (default: localhost with a random free port)
--web-open Open the web UI in the default browser on start (default true)
--write-config Write current configuration to file (default is $HOME/.gdu.yaml)
Basic list of actions in interactive mode (show help modal for more):
↑ or k Move cursor up
↓ or j Move cursor down
→ or Enter or l Go to highlighted directory
← or h Go to parent directory
d Delete the selected file or directory
D Move the selected file or directory to trash
e Empty the selected directory
n Sort by name
s Sort by size
c Show/hide item count
? Show help modal
Examples
gdu # analyze current dir
gdu -a # show apparent size instead of disk usage
gdu --exclusive-size # on XFS/btrfs: count only bytes not shared by reflinks
gdu --no-delete # prevent write operations
gdu --no-view-file # prevent viewing file contents
gdu --trash-command 'trash-put --trash-dir ~/mytrash' # use own trash command for the D key
gdu --trash-command 'mv -f "$1" ~/mytrash/' # trash by moving items with mv
gdu --shell /usr/bin/fish # set the shell spawned with the b key
gdu <some_dir_to_analyze> # analyze given dir
gdu dir_a dir_b dir_c # analyze several dirs at once
gdu -d # show all mounted disks
gdu -l ./gdu.log <some_dir> # write errors to log file
gdu -i /sys,/proc / # ignore some paths
gdu -I '.*[abc]+' # ignore paths by regular pattern
gdu -X ignore_file / # ignore paths by regular patterns from file
gdu -G .gitignore / # ignore dirs by .gitignore-style patterns from file
gdu -c / # use only white/gray/black colors
gdu -n / # only print stats, do not start interactive mode
gdu --interactive / | tee out.txt # force interactive mode even when stdout is piped
gdu -p / # do not show progress, useful when using its output in a script
gdu -ps /some/dir # show only total usage for given dir
gdu -t 10 / # show top 10 largest files
gdu --reverse-sort -n / # show files sorted from smallest to largest in non-interactive mode
gdu / > file # write stats to file, do not start interactive mode
gdu -o- / | gzip -c >report.json.gz # write all info to JSON file for later analysis
zcat report.json.gz | gdu -f- # read analysis from file
gdu --db=tmp.badger / # use persistent key-value storage for saving analysis data
gdu --db=tmp.db / # use persistent SQLite storage for saving analysis data
gdu -r / # read saved analysis data from persistent key-value storage
gdu --web / # analyze and browse the results in a web browser
gdu --web --web-listen localhost:8080 / # serve the web UI on a fixed address
gdu --web --web-open=false / # print the URL but do not open a browser
Scanning multiple directories
More than one directory can be given on the command line, which is useful when only a subset of a large directory is of interest:
gdu ~/projects/alpha ~/projects/beta ~/projects/gamma
The directories are scanned one after another and presented together under a virtual top level directory named (multiple), so they can be compared and sorted like ordinary siblings. They are listed by their absolute path, so directories that share a base name stay distinguishable. Each of them keeps its real path, so rescanning, deletion and opening a shell work as usual once you navigate into one of them.
The virtual top level directory itself has no counterpart on disk, so operations that need a real path are unavailable while it is shown: --change-cwd, spawning a shell, browsing to the parent directory (--browse-parent-dirs) and exporting to JSON. Rescanning it rescans every directory below it.
Directories that are nested in one another are rejected, since scanning both would count the nested part twice. Exporting (-o) and database storage (--db) accept a single directory only.
Modes
Gdu has three modes: interactive (default), non-interactive and export.
Non-interactive mode is started automatically when TTY is not detected (using go-isatty), for example if the output is being piped to a file, or it can be started explicitly by using a flag. Use --interactive to disable this automatic fallback and force interactive mode.
In non-interactive mode (and without --top and --depth flags), gdu uses a memory-efficient analyzer that only tracks top-level directory totals.
This means memory usage stays constant regardless of how large the scanned directory tree is.
When --top or --depth flags are used, the full directory tree is built in memory as in interactive mode.
Export mode (flag -o) outputs all usage data as JSON, which can be later opened using the -f flag. In interactive mode, press Esc or Ctrl+C during a scan to stop scheduling new work and keep the results found so far; pressing Ctrl+C again while the scan is stopping quits gdu. If you would rather have the first Ctrl+C quit gdu outright, use --ctrl-c-quits; Esc keeps working either way.
By default the export includes every attribute, and directories always carry their asize, dsize, and items summary stats so they can be preserved on import. Use --output-attrs=asize,dsize to emit only selected optional attributes; name is always included. Available attributes are asize, dsize, shsize, items, mtime, notreg, and ino. A directory that could not be read in full carries "read_error":true.
Gdu honors BLOCK_SIZE and BLOCKSIZE in terminal output. BLOCK_SIZE takes precedence; both accept GNU coreutils block-size values such as 1K, kB, human-readable, and si. Explicit size-format flags override these environment variables. Exported JSON always retains raw byte values.
Hard links are counted only once.
Web UI
Gdu can serve a browser-based interface instead of the terminal UI. Run:
gdu --web /some/dir
Gdu scans the directory, prints the URL, and (by default) opens it in your
default browser. The interface shows an animated donut chart of the current
directory’s contents alongside a sortable table with size bars, breadcrumb
navigation, and a disk-usage/apparent-size toggle. Switch to the full-window
treemap to explore the complete nested subtree, select files or directories,
and double-click a directory to open it. Details too small to display are
folded into their nearest visible parent directory. Scan progress is streamed
live while the analysis runs.
In the treemap, press O to reveal the selected item in the system file
manager, D (or Delete) to permanently delete it after confirmation, or ?
to show the keyboard shortcuts. In the donut view, each row of the table has
its own reveal and delete buttons that act on that item; deletion asks for
confirmation with the same dialog. The deletion dialog can suppress further
confirmations for the current browser session, for both the treemap and the
table, so with “permanent” chosen a single click on a row’s delete button
deletes immediately. Deletion runs in the background: the item is drawn
hatched right away, more items can be deleted meanwhile, and a failed deletion
puts the item back with the reason. A deleted item stays in place,
cross-hatched, so the layout does not jump; the directory is reloaded when you
open another one. You can keep browsing while deletions run; an item that is
being deleted cannot be opened. The --no-delete flag and
filtered-scan deletion restrictions apply to the web UI as well as the
terminal UI. Reveal remains available with --no-delete because it does not
modify scanned data. To deliberately allow deletion while filters are active,
set GDU_ALLOW_DELETE_WITH_FILTER=1; the displayed tree may then omit files
that are still present on disk.
Cleanup projections
The treemap’s projection selector (or P) recolors it to help free space
without touching anything important. Area always stays size.
- Location - the default coloring by top-level directory.
- Cleanup - everything grey except cleanup candidates: strong orange for
safe ones (regenerated by their tool, e.g.
node_modules next to
package.json, target next to Cargo.toml, __pycache__, the Go, Gradle,
Cargo, npm, uv and Homebrew caches, app caches)
and muted gold for ones to review first (downloaded ML models, installed
toolchains such as ~/.rustup or ~/.nvm, installers,
virtualenvs, dist/build, git-ignored files). A directory is tinted by the
share of candidates inside it, including files too small to draw.
- Age - colored by the latest change inside an item.
- By category - candidates within the current directory regrouped by
category, so cache space scattered over many small directories shows up as
one block.
The legend shows how much each category takes within the current directory;
click a category to single it out: its items are drawn in the category’s color
and outlined, everything else fades (Esc shows all again). Hovering a candidate
shows what it is and how to remove it cleanly (e.g. ollama rm for Ollama
models). Build-like directories only count next to a project marker, and
anything ignored by a repository’s .gitignore is flagged for review (ignored
dist/build output counts as safe). Candidates are found in the background
after a scan, while the header shows “classifying…”. They are only
highlighted: deleting stays a deliberate action.
Paths can be excluded and rules added in the cleanup section of the config
file, see configuration.md:
cleanup:
exclude: [~/work/current-project]
By default the server binds to localhost on a random free port. Use
--web-listen (or the web.listen config option) to pin a fixed address.
The compiled web assets are embedded in the binary, so no extra files or network
access are required.
Security: browsing is read-only and requires no authentication, so anyone
who can reach the port sees file names and sizes - keep it bound to
localhost (the default). Reveal and delete actions need more: a request
that both originates from a loopback address and carries a random token,
generated fresh for each server run and never served over the API. The URL is
printed to this process’s terminal and passed to the configured browser
launcher. On Linux, a cold-started browser may retain that URL in its
world-readable command line; custom browser commands may do the same on any
platform. On a multi-user machine, use --web-open=false and open the printed
URL from an already-running browser. Pages on another origin or browser tab
are rejected even if they can reach the port. Binding to a non-loopback address
makes scan details reachable by other hosts on the network and prints a
warning.
File flags
Files and directories may be prefixed by a one-character
flag with following meaning:
-
! An error occurred while reading this directory.
-
. An error occurred while reading a subdirectory, size may be not correct.
-
@ File is symlink or socket. Symlinks can be shown as name -> target (the link target is displayed next to the name, like ls -l).
-
H Same file was already counted (hard link).
-
e Directory is empty.
Reflinks and shared extents
On filesystems with reflink support (XFS, btrfs, bcachefs, …) many files can
share the same data. Disk usage as reported by stat counts shared data once
per file, so the sum can exceed what the filesystem uses and deleting a file
frees less than its size.
With --exclusive-size (Linux only) Gdu asks the kernel for each regular file’s
extent map (FS_IOC_FIEMAP) and reports the total length of the extents that
are not flagged as shared. That is what deleting the file would free, ignoring
what other files still reference. It replaces the disk usage figure, so sorting,
size bars, totals and -o exports (dsize) all use it; apparent size
(-a) is unchanged. Details:
- Data shared with another file counts as zero in every file sharing it, so a
directory holding only the clones of a file elsewhere shows nothing, and the
last copy standing shows its full size only once the others are gone.
- On btrfs, data shared with a snapshot is flagged as shared too, so files in a
snapshotted subvolume count as zero until they are changed. Deleting them
frees nothing while the snapshot still holds the data.
- Holes in sparse files count as nothing. Preallocated, delayed-allocation and
inline extents count as the file’s own unless they are flagged as shared.
Sizes are logical: compressed extents (btrfs, …) are counted uncompressed.
- Hard links are counted once, as without the flag.
- Where FIEMAP cannot be used (unsupported filesystem such as tmpfs or NFS, the
file cannot be opened, …) the file keeps its allocated-blocks figure.
Files and filesystems that do not report shared extents (ext4) show close to
the same figure as without the flag: the extent map leaves out the blocks the
filesystem keeps for its own bookkeeping, such as extent trees and extended
attributes. Symlinks and directories are not measured, and neither are
archives shown by their contents (
--archive-browsing). Other platforms
ignore the option without a warning, so a configuration file can be shared
between machines.
- It costs an
open and at least one ioctl per file with allocated blocks.
Once a filesystem has refused FIEMAP, the rest of its files are not asked.
- The exported
dsize does not record which metric produced it. Each file
whose extent map was read and has shared extents also carries shsize, the
bytes in those extents, so an export holds both halves of the file’s
allocated data. Readers that do not know the key ignore it. Directories do
not add shsize up, and the SQLite storage (--db *.sqlite) does not keep
it, so exports made with it have none.
Configuration file
Gdu can read (and write) YAML configuration file.
$HOME/.config/gdu/gdu.yaml and $HOME/.gdu.yaml are checked for the presence of the config file by default.
See the full list of all configuration options.
Examples
- To configure gdu to permanently run in gray-scale color mode:
echo "no-color: true" >> ~/.gdu.yaml
- To set default sorting in configuration file:
sorting:
by: name // size, name, itemCount, mtime
order: desc
- To configure gdu to set CWD variable when browsing directories:
echo "change-cwd: true" >> ~/.gdu.yaml
- To set the shell spawned with the
b key:
echo "shell: /usr/bin/fish" >> ~/.gdu.yaml
- To configure the web UI (bind address and browser behavior):
web:
listen: "localhost:8080" # empty (default) = localhost + random free port
open-browser: true # open the default browser on start
browser: "" # override launcher command; empty = OS default
- To save the current configuration
gdu --write-config
Styling
There are wide options for how terminals can be colored.
Some gdu primitives (like basic text) adapt to different color schemas, but the selected/highlighted row does not.
If the default look is not sufficient, it can be changed in configuration file, e.g.:
style:
selected-row:
text-color: black
background-color: "#ff0000"
marked:
text-color: white
background-color: "#6600cc"
Deletion in background and in parallel (experimental)
Gdu can delete items in the background, thus not blocking the UI for additional work.
To enable:
echo "delete-in-background: true" >> ~/.gdu.yaml
Directory items can be also deleted in parallel, which might increase the speed of deletion.
To enable:
echo "delete-in-parallel: true" >> ~/.gdu.yaml
Saving analysis data to database
Gdu can store the analysis data to a database file instead of just memory.
This allows you to save and reload analysis results later.
Both SQLite and BadgerDB are supported.
gdu --db analysis.sqlite / # saves analysis data to SQLite database
gdu --db analysis.badger / # saves analysis data to BadgerDB
gdu -r --db analysis.sqlite / # reads saved data, does not run analysis again
Running tests
make install-dev-dependencies
make test
Profiling
Gdu can collect profiling data when the --enable-profiling flag is set.
The data are provided via embedded http server on URL http://localhost:6060/debug/pprof/.
You can then use e.g. go tool pprof -web http://localhost:6060/debug/pprof/heap
to open the heap profile as SVG image in your web browser.
Benchmarks
Benchmarks were performed on 90G directory (100k directories, 400k files) on 500 GB SSD using hyperfine.
See benchmark target in Makefile for more info.
Cold cache
Filesystem cache was cleared using sync; echo 3 | sudo tee /proc/sys/vm/drop_caches.
| Command |
Mean [s] |
Min [s] |
Max [s] |
Relative |
diskus ~ |
4.489 ± 0.020 |
4.449 |
4.516 |
1.00 |
gdu -npc ~ |
4.716 ± 0.342 |
4.109 |
5.337 |
1.05 ± 0.08 |
GOMAXPROCS=80 gdu -npc ~ |
4.901 ± 1.953 |
3.627 |
9.993 |
1.09 ± 0.44 |
pdu ~ |
5.969 ± 0.492 |
5.567 |
6.640 |
1.33 ± 0.11 |
dua ~ |
6.030 ± 0.249 |
5.878 |
6.597 |
1.34 ± 0.06 |
dust -d0 ~ |
6.181 ± 0.311 |
6.043 |
7.053 |
1.38 ± 0.07 |
gdu -npc --db=tmp.badger ~ |
27.479 ± 3.015 |
25.048 |
32.777 |
6.12 ± 0.67 |
du -hs ~ |
30.608 ± 0.221 |
30.136 |
30.794 |
6.82 ± 0.06 |
duc index ~ |
32.897 ± 3.168 |
31.524 |
41.865 |
7.33 ± 0.71 |
ncdu -0 -o /dev/null ~ |
33.163 ± 3.482 |
31.476 |
42.979 |
7.39 ± 0.78 |
gdu -npc --db=tmp.db ~ |
44.989 ± 0.270 |
44.622 |
45.414 |
10.02 ± 0.07 |
Warm cache
| Command |
Mean [ms] |
Min [ms] |
Max [ms] |
Relative |
diskus ~ |
270.8 ± 8.1 |
262.4 |
291.5 |
1.00 |
pdu ~ |
299.1 ± 4.1 |
292.1 |
305.0 |
1.10 ± 0.04 |
GOMAXPROCS=100 gdu -npc ~ |
459.1 ± 14.2 |
446.7 |
490.3 |
1.69 ± 0.07 |
gdu -npc ~ |
466.1 ± 27.9 |
421.4 |
495.3 |
1.72 ± 0.12 |
dua ~ |
590.6 ± 5.9 |
580.5 |
599.7 |
2.18 ± 0.07 |
dust -d0 ~ |
578.7 ± 3.7 |
572.2 |
586.3 |
2.14 ± 0.07 |
du -hs ~ |
1255.2 ± 7.4 |
1245.1 |
1273.4 |
4.63 ± 0.14 |
duc index ~ |
1450.5 ± 6.2 |
1440.6 |
1460.4 |
5.36 ± 0.16 |
ncdu -0 -o /dev/null ~ |
2222.4 ± 5.6 |
2215.6 |
2231.0 |
8.21 ± 0.25 |
gdu -npc --db=tmp.db ~ |
8246.7 ± 30.9 |
8181.9 |
8288.7 |
30.45 ± 0.92 |
gdu -npc --db=tmp.badger ~ |
15608.0 ± 3215.8 |
13960.3 |
22448.0 |
57.63 ± 12.00 |
Alternatives
- ncdu - NCurses based tool written in pure
C (LTS) or zig (Stable)
- godu - Analyzer with a carousel like user interface
- dua - Tool written in
Rust with interface similar to gdu (and ncdu)
- diskus - Very simple but very fast tool written in
Rust
- duc - Collection of tools with many possibilities for inspecting and visualising disk usage
- dust - Tool written in
Rust showing tree like structures of disk usage
- pdu - Tool written in
Rust showing tree like structures of disk usage
Notes
HDD icon created by Nikita Golubev - Flaticon
![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)
评论