Home

Awesome

btdu - sampling disk usage profiler for btrfs

<img align="right" src="https://dump.cy.md/a8e2054ffc05bc120b390e48c6d4e43d/19%3A02%3A24-upload.png">

Some btrfs features may make it difficult to estimate what disk space is being used for:

For these reasons, classic disk usage analyzers such as ncdu cannot provide an accurate depiction of actual disk usage. (btrfs compression in particular is challenging to classic analyzers, and special tools must be used to query compressed usage.)

btdu is a sampling disk usage profiler for btrfs. It works according to the following algorithm:

  1. Pick a random point on the disk in use
  2. Find what is located at that point
  3. Add the path to the results
  4. Repeat the above steps indefinitely

Though it works by taking random samples, it is "eventually" accurate.

It differs from classic analyzers through the following properties:

Use cases

Installation

<a href="https://repology.org/project/btdu/versions"><img align="right" src="https://repology.org/badge/vertical-allrepos/btdu.svg" alt="Packaging status" title="Packaging status"></a>

btdu can be installed in one of the following ways:

Building

  1. Install a D compiler.
    Note that you will need a compiler supporting D v2.097 or newer - the compiler in your distribution's repositories might be too old.
  2. Install Dub, if it wasn't included with your D compiler.
  3. Install libncursesw5-dev, or your distribution's equivalent package.
  4. Run dub build -b release

Usage

Run btdu with root privileges as follows:

# btdu /path/to/filesystem/root

Note: The indicated path must be to the top-level subvolume (otherwise btdu will be unable to open other subvolumes for inode resolution). If in doubt, mount the filesystem to a new mountpoint with -o subvol=/,subvolid=5.

You can start browsing the results instantly; btdu will keep collecting samples to improve accuracy until it is stopped by quitting or pausing (which you can do by pressing <kbd>p</kbd>).

Run btdu --help for more usage information.

See CONCEPTS.md for information about some btdu / btrfs concepts, such as represented / exclusive / shared size.

Headless mode

With the --headless switch, btdu will run without the user interface. This is useful together with the --export option, which saves results to a file that can later be viewed in the UI using the --import option. For automated invocations, don't forget to specify a stop condition such as --max-time.

Example:

# btdu --headless --export=results.json --max-time=10m /path/to/filesystem/root
$ btdu --import results.json

Deleting

You can delete the selected file or directory from the filesystem by pressing <kbd>d</kbd> then <kbd>⇧ Shift</kbd><kbd>Y</kbd>. This will recursively delete the file or directory shown as "Full path".

Deleting files during a btdu run (whether via btdu or externally) skews the results. When deleting files from btdu, it will make a best-effort attempt to adjust the results to match. Statistics such as exclusive size may be inaccurate. Re-run btdu to obtain fresh results.

Marking

You can mark or unmark items under the cursor by pressing the space bar.

Press <kbd>⇧ Shift</kbd><kbd>M</kbd> to view all marks, and <kbd>⇧ Shift</kbd><kbd>D</kbd> then <kbd>⇧ Shift</kbd><kbd>Y</kbd> to delete all marked items.

Press <kbd>*</kbd> to invert marks on the current screen.

Marks are saved in exported .json files; a boolean field named "mark" will be present on marked nodes. Press <kbd>⇧ Shift</kbd><kbd>O</kbd> to save an export file during an interactive session.

License

btdu is available under the GNU GPL v2. (The license is inherited from btrfs-progs.)

See Also