{"id":21483342,"url":"https://github.com/cybershadow/btdu","last_synced_at":"2026-01-02T13:22:10.687Z","repository":{"id":41508747,"uuid":"310572026","full_name":"CyberShadow/btdu","owner":"CyberShadow","description":"sampling disk usage profiler for btrfs","archived":false,"fork":false,"pushed_at":"2025-02-05T05:41:47.000Z","size":517,"stargazers_count":482,"open_issues_count":9,"forks_count":6,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-03-16T22:52:48.504Z","etag":null,"topics":["btrfs"],"latest_commit_sha":null,"homepage":"","language":"D","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CyberShadow.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-06T11:01:10.000Z","updated_at":"2025-03-16T18:58:59.000Z","dependencies_parsed_at":"2023-02-08T12:31:39.851Z","dependency_job_id":"8282bc87-06cc-41b2-a5af-63c3309ce29c","html_url":"https://github.com/CyberShadow/btdu","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CyberShadow%2Fbtdu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CyberShadow%2Fbtdu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CyberShadow%2Fbtdu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CyberShadow%2Fbtdu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CyberShadow","download_url":"https://codeload.github.com/CyberShadow/btdu/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244006303,"owners_count":20382444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["btrfs"],"created_at":"2024-11-23T12:46:32.507Z","updated_at":"2026-01-02T13:22:10.680Z","avatar_url":"https://github.com/CyberShadow.png","language":"D","funding_links":[],"categories":[],"sub_categories":[],"readme":"btdu - sampling disk usage profiler for btrfs\n=============================================\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://dump.cy.md/e17c462459de465a66f2d511f3201866/btdu_0_6.png\"\u003e\n\u003c/p\u003e\n\nSome [btrfs](https://btrfs.wiki.kernel.org/) features may make it difficult to estimate what disk space is being used for:\n\n- **Subvolumes** allow cheap copy-on-write snapshots of entire filesystem trees, with unmodified data being shared among snapshots\n- **File and extent cloning** allow creating cheap copies of files or parts thereof, with extents being stored only once\n- **Compression** transparently allows further reducing disk usage\n\nFor these reasons, classic disk usage analyzers such as [ncdu](https://dev.yorhel.nl/ncdu) cannot provide an accurate depiction of actual disk usage. (btrfs compression in particular is challenging to classic analyzers, and [special tools](https://github.com/kilobyte/compsize) must be used to query compressed usage.)\n\n**btdu** is a sampling disk usage profiler for btrfs. It works according to the following algorithm:\n\n1. Pick a random point on the disk in use\n2. Find what is located at that point\n3. Add the path to the results\n4. Repeat the above steps indefinitely\n\nThough it works by taking random samples, it is \"eventually\" accurate.\n\nIt differs from classic analyzers through the following properties:\n\n- btdu starts showing results instantly. Though wildly inaccurate at first, they become progressively more accurate the longer btdu is allowed to run.\n- btdu analyzes entire filesystems only. There is no way to analyze only a particular subdirectory or subvolume.\n- btdu counts extents used by multiple files only once. (The shortest path is used when placing the sample in the tree for visualization.)\n- By nature of its algorithm, btdu works correctly with compression and other btrfs filesystem features.\n- Because it queries raw filesystem metadata, btdu requires root privileges to run.\n\n\nUse cases\n---------\n\n- **Quickly summarize space usage**\n\n  btdu needs to collect only 100 samples to achieve a ~1% resolution, which means it can identify space hogs very quickly. This is useful if the disk is full, and some space must be freed urgently to restore normal operation.\n\n- **Estimate snapshot size**\n\n  When an extent is in use by multiple files or snapshots, to decide where to place it in the browsable tree, btdu picks the path with the shortest length, or the lexicographically smaller path if the length is the same. An emergent effect of this property is that it can be used to estimate snapshot size, if your snapshots use a fixed-length lexicographically-ordered naming scheme (such as e.g. YYYY-MM-DD-HH-MM-SS): the size of snapshots displayed in btdu will thus indicate data that occurs in that snapshot or any later one, i.e. the amount of \"new\" data in that snapshot.\n\n- **Estimate compressed data size**\n\n  If you use btrfs data compression (whether to save space, improve performance, or conserve flash writes), btdu can be used to estimate how much real disk space compressed data uses.\n\n- **Estimate unreachable extent size**\n\n  A feature unique to btdu is the ability to estimate the amount of space used by unreachable parts of extents, i.e. data in extents containing older versions of file content which has since been overwritten. This btrfs \"dark matter\" can be an easily overlooked space hog, which can be eliminated by rewriting or defragmenting affected files.\n\n- **Understand btrfs space usage**\n\n  btdu shows explanations for hierarchy objects and common errors, which can help understand how btrfs uses disk space. The `--expert` mode enables the collection and display of [additional size metrics](CONCEPTS.md#size-metrics), providing more insight into the allocation of objects with non-trivial sharing. [Logical and physical sampling modes](CONCEPTS.md#logical-vs-physical-space) can help understand RAID space usage, especially when using multiple profiles.\n\n- **Track disk usage changes over time**\n\n  Using `--compare`, btdu can compare current disk usage against a previously exported baseline, showing what has grown or shrunk. This helps identify active space consumers (files or directories that are *accumulating* data) rather than just showing what currently uses the most space. Useful for finding runaway logs, growing caches, or verifying that cleanup operations had the intended effect.\n\n\nInstallation\n------------\n\n\u003ca href=\"https://repology.org/project/btdu/versions\"\u003e\u003cimg align=\"right\" src=\"https://repology.org/badge/vertical-allrepos/btdu.svg\" alt=\"Packaging status\" title=\"Packaging status\"\u003e\u003c/a\u003e\n\nbtdu can be installed in one of the following ways:\n\n- Via package manager, if it is packaged by your distribution (see on the right).\n- Download a static binary from [the releases page](https://github.com/CyberShadow/btdu/releases)\n  or [the latest CI run](https://github.com/CyberShadow/btdu/actions?query=branch%3Amaster).\n- Using Nix: `nix run github:CyberShadow/btdu` (or `nix profile install github:CyberShadow/btdu` for permanent installation).\n- Clone this repository and build from source (see below).\n\n\nBuilding\n--------\n\n### Using Nix\n\nIf you have [Nix](https://nixos.org/) installed with flakes enabled:\n\n    nix build github:CyberShadow/btdu\n\nOr from a local clone:\n\n    nix build\n\nThe binary will be available at `./result/bin/btdu`.\n\nFor development, use `nix develop` to enter a shell with all dependencies available, then build with `dub build`.\n\n### Manual build\n\n1. Install [a D compiler](https://dlang.org/download.html).  \n   Note that you will need a compiler supporting D v2.097 or newer - the compiler in your distribution's repositories might be too old.\n2. Install [Dub](https://github.com/dlang/dub), if it wasn't included with your D compiler.\n3. Install `libncursesw5-dev`, or your distribution's equivalent package.\n4. Run `dub build -b release`\n\n\nUsage\n-----\n\nRun btdu with root privileges as follows:\n\n    # btdu /path/to/filesystem/root\n\nNote: 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`.\n\nRun `btdu --help` for more usage information.\n\n### Interactive mode\n\nBy default, btdu launches a terminal user interface where you can browse the results interactively. btdu will keep collecting samples to improve accuracy until it is stopped by quitting or pausing (which you can do by pressing \u003ckbd\u003ep\u003c/kbd\u003e).\n\n### Headless mode\n\nWith the `--headless` switch, btdu runs without the interactive UI and prints a tree of the largest items to stdout:\n\n    # btdu --headless --max-time=30s /mnt/btrfs\n    /mnt/btrfs (~97.56 GiB)\n    ├── @home (~45.23 GiB)\n    │   ├── user (~30.12 GiB)\n    │   └── .cache (~12.34 GiB)\n    └── @root (~35.78 GiB)\n\nThis is useful for quickly getting an overview without launching the full UI. Only nodes representing more than 1% of total space are shown.\n\nIn `--expert` mode, four size columns are displayed (represented, distributed, exclusive, shared):\n\n    # btdu --headless --expert --max-time=30s /mnt/btrfs\n\nIn `--compare` mode, a delta column is displayed showing size changes:\n\n    # btdu --headless --compare=baseline.json --max-time=30s /mnt/btrfs\n\nFor automated invocations or scripting, combine with `--export` to save results to a file that can later be viewed in the UI:\n\n    # btdu --headless --export=results.json --max-time=10m /mnt/btrfs\n    $ btdu --import results.json\n\n### Sampling options\n\n`--expert` collects additional metrics; `--physical` switches the addressing mode from logical to physical, causing btdu to measure physical disk space.\n\nUse `--prefer=PATTERN` and `--ignore=PATTERN` to control which path represents shared extents. Patterns are absolute filesystem paths (supporting glob syntax: `*`, `**`, etc.) and must be under the sampled filesystem root. Example: `--prefer=/mnt/btrfs/data/.snapshots`. Interactively, you can do this by pressing \u003ckbd\u003e⇧ Shift\u003c/kbd\u003e\u003ckbd\u003eP\u003c/kbd\u003e and \u003ckbd\u003e⇧ Shift\u003c/kbd\u003e\u003ckbd\u003eI\u003c/kbd\u003e respectively.\n\n`--max-samples`, `--max-time`, and `--min-resolution` control when btdu stops sampling (and, in headless mode, exits).\n\nSee [CONCEPTS.md](CONCEPTS.md) for more information about btdu / btrfs concepts, such as represented / exclusive / shared size.\n\n### Deleting\n\nYou can delete the selected file or directory from the filesystem by pressing \u003ckbd\u003ed\u003c/kbd\u003e then \u003ckbd\u003e⇧ Shift\u003c/kbd\u003e\u003ckbd\u003eY\u003c/kbd\u003e. This will recursively delete the file or directory shown as \"Full path\".\n\nDeleting 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.\n\n### Marking\n\nYou can mark or unmark items under the cursor by pressing the space bar.\n\nPress \u003ckbd\u003e⇧ Shift\u003c/kbd\u003e\u003ckbd\u003eM\u003c/kbd\u003e to view all marks, and \u003ckbd\u003e⇧ Shift\u003c/kbd\u003e\u003ckbd\u003eD\u003c/kbd\u003e then \u003ckbd\u003e⇧ Shift\u003c/kbd\u003e\u003ckbd\u003eY\u003c/kbd\u003e to delete all marked items.\n\nPress \u003ckbd\u003e*\u003c/kbd\u003e to invert marks on the current screen.\n\nIn [`--expert` mode](CONCEPTS.md#size-metrics), btdu will show the total exclusive size of (i.e. how much would be freed by deleting) the marked items it the top status bar.\n\nMarks are saved in exported `.json` files; a boolean field named `\"mark\"` will be present on marked nodes.\n\n### Import and export\n\nPress \u003ckbd\u003e⇧ Shift\u003c/kbd\u003e\u003ckbd\u003eO\u003c/kbd\u003e to save an export file during an interactive session; alternatively, pass `--export=FILENAME` to do so automatically on exit.\n\nExports can be loaded with `--import`. Then, specify a file name instead of the filesystem path to sample.\n\nbtdu supports two re-importable export formats:\n\n- **Binary** (`.btdu`): Compact, efficient format that preserves all sampling data losslessly. The binary format always contains complete data regardless of `--expert` mode; the `--expert` flag is specified at import time to control whether expert metrics are displayed (which uses more memory). Recommended for backups and comparisons.\n\n- **JSON** (`.json`): Text-based format that can be processed by external tools and scripts. With `--expert`, the JSON output is larger as it captures additional sampling statistics. Without `--expert`, only basic metrics are included.\n\nThe format is auto-detected from the file extension, or can be specified explicitly with `--export-format`.\n\nFor a more portable (but less detailed) export, use `--du`; the resulting file should then be loadable by any disk usage analyzer which supports loading `du` output.\n\n### Comparing\n\nUse `--compare=BASELINE` to compare against a previously exported baseline (in JSON or binary format). btdu will show size deltas instead of absolute sizes, making it easy to see what has grown or shrunk.\n\nFor the most accurate comparisons, use deterministic sampling parameters: `-j1` (single process) and `--max-samples` (rather than `--max-time`). Use the same parameters when creating both exports being compared.\n\nCompare live sampling against a baseline:\n\n    # btdu -j1 --max-samples=10000 /mnt/btrfs --export=baseline.btdu --headless\n    # ... time passes, changes are made ...\n    # btdu -j1 --max-samples=10000 /mnt/btrfs --compare=baseline.btdu\n\nCompare two exported snapshots:\n\n    $ btdu --import new.btdu --compare=old.btdu\n\nPress \u003ckbd\u003ec\u003c/kbd\u003e to sort by delta (largest changes first), and \u003ckbd\u003es\u003c/kbd\u003e to sort by absolute current size.\n\nLicense\n-------\n\n`btdu` is available under the [GNU GPL v2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html). (The license is inherited from btrfs-progs.)\n\n\nSee Also\n--------\n\n* [btsdu](https://github.com/rkapl/btsdu), the Btrfs Snapshot Disk Usage Analyzer\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcybershadow%2Fbtdu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcybershadow%2Fbtdu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcybershadow%2Fbtdu/lists"}