gdu: Open Source System Cleanup & Optimization

What is gdu?

gdu (go DiskUsage()) is a fast disk usage analyzer with a console interface written in Go, aimed at developers, system administrators and other terminal users who need to find out what is consuming space on a disk.

What it is

gdu — short for go DiskUsage() — is a disk usage analyzer that runs in the console and reports how much space directories and files occupy, with an interactive browsing mode and a non-interactive reporting mode. It is written in Go and published under the MIT licence, and it sits in the command-line productivity and system cleanup ecosystem as a tool for inspecting filesystem usage rather than for editing files.

It exists because working out which directories have filled a disk by hand is slow. Walking a large tree with generic shell tooling serialises the work and gives no interactive way to drill down into a result. gdu replaces that manual, one-command-at-a-time inspection with a scanner built around parallel processing: the README states it is intended primarily for SSD disks, where it can fully utilize parallel processing, and that HDDs work as well although the performance gain is not so huge. Its concrete output is either an interactive console view or structured JSON that other tooling can consume.

Key capabilities

Runs both interactively and non-interactively, with -n, --non-interactive for scripted runs and --interactive to force the interactive mode even when output is not a TTY.
Scans in parallel across cores; -m, --max-cores caps this (8 cores available by default) and --sequential switches to sequential scanning for rotating HDDs.
Stores analyses persistently via -D, --db using SQLite (.sqlite) or BadgerDB (.badger), and -r, --read-from-storage reads an existing database instead of re-scanning.
Imports and exports JSON: -o, --output-file exports all info as JSON, --output-attrs selects exported attributes (name, asize, dsize, items, mtime, notreg), and -f, --input-file imports an analysis back in.
Browses archives with --archive-browsing for zip, jar, tar, tar.gz, tar.bz2 and tar.xz files, and --collapse-path collapses single-child directory chains.
Controls scan scope with -i, --ignore-dirs (default /proc, /dev, /sys, /run), -I, --ignore-dirs-pattern, -X, --ignore-from, -E, --exclude-type, -x, --no-cross for filesystem boundaries, and --min-age / --max-age for mtime windows.
Reads behaviour from --config-file (default $HOME/.gdu.yaml), restricts destructive or exposing actions with --no-delete, --no-spawn-shell and --no-view-file, and exposes profiling data on http://localhost:6060/debug/pprof/ when --enable-profiling is set.

Who uses it and how

System administrators facing a filling disk on a server, who point it at a directory, browse the largest directories interactively and then act on what they find.
Operators who scan a host filesystem from a container, using the published image with the host root mounted, for example docker run --rm --init --interactive --tty --privileged --volume /:/mnt/root ghcr.io/dundee/gdu /mnt/root. That invocation runs privileged and mounts the host root, so it grants the container broad access to the host filesystem.
Teams wiring cleanup or reporting into scripts, using non-interactive mode together with JSON export to feed other tooling.
Anyone comparing the state of a filesystem over time, by storing a SQLite or BadgerDB database and re-reading it later instead of rescanning.
Contributors, as the project carries the hacktoberfest topic alongside cli, disk-usage, filesystem and golang.

Getting started

Download the binary for your system from the releases page, or install by curl with curl -L https://github.com/dundee/gdu/releases/latest/download/gdu_linux_amd64.tgz | tar xz, then chmod +x gdu_linux_amd64 and move it to /usr/bin/gdu. The INSTALL.md page lists other ways to install it to your system.

How it compares

The facts provide no list of paid products that gdu displaces, and they name no comparable tools, so it stands alone in this registry on its own terms as an MIT-licensed Go command-line utility. Any comparison beyond that would have to be made against tools this entry does not describe.

When to use it — and when not to

A self-hoster must operate very little: gdu is a command-line binary, and the SQLite or BadgerDB database used by -D, --db and -r, --read-from-storage is optional and file-backed, with configuration read from $HOME/.gdu.yaml. It is a poor fit for people who want a graphical desktop interface or a hosted service, and the container route requires mounting the host root and running privileged, which is a real security consideration rather than a convenience. The README excerpt supplied here is cut off partway through the flag list, so some documented options are not visible from this entry.

project readme (upstream, from github) — read inline

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)
  -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
  -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,items,mtime,notreg)
  -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 sorting order (smallest to largest) in non-interactive mode
      --sequential                    Use sequential scanning (intended for rotating HDDs)
  -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 --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              # 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            # 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 -c /                              # use only white/gray/black colors

gdu -n /                              # only print stats, do not start interacti

Frequently asked questions

Is gdu free to use?

gdu is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does gdu do?

Fast disk usage analyzer with console interface written in Go

What is gdu written in?

gdu is primarily written in Go. Its source is publicly available at https://github.com/dundee/gdu, and it has 5,982 GitHub stars.