# info > BTRFS-FILESYSTEM

---
type: CommandReference
command: btrfs-filesystem
mode: man
section: 8
source: man-pages
---

## Quick Reference
- `btrfs filesystem df /mnt` — Show space allocation summary
- `btrfs filesystem usage /mnt` — Detailed filesystem usage (preferred over `df`)
- `btrfs filesystem defrag -r /path` — Recursively defragment files
- `btrfs filesystem resize -1G /mnt` — Shrink filesystem by 1 GiB
- `btrfs filesystem resize max /mnt` — Grow filesystem to maximum device size
- `btrfs filesystem label /dev/sda1 "mylabel"` — Set or show filesystem label
- `btrfs filesystem show` — Show all BTRFS filesystems
- `btrfs filesystem sync /mnt` — Sync and start cleanup of deleted subvolumes

## Name
btrfs-filesystem — command group for whole filesystem operations

## Synopsis
`btrfs filesystem <subcommand> <args>`

## Subcommands

### `df [options] <path>`
Show a terse summary of block group allocation. The output includes `Data`, `Metadata`, `System`, and `GlobalReserve` with their profile (e.g. `single`), `total` space, and `used` space. `GlobalReserve` is an internal emergency space (portion of Metadata) used when the filesystem is full; its size is dynamic, usually ≤512 MiB.

**Options** (unit display; last conflicting option wins)
- `-b`, `--raw` — raw numbers in bytes, no `B` suffix
- `-h`, `--human-readable` — human friendly, base 1024 (default)
- `-H` — human friendly, base 1000
- `--iec` — select 1024 base for following options
- `--si` — select 1000 base for following options
- `-k`, `--kbytes` — KiB (or kB with `--si`)
- `-m`, `--mbytes` — MiB (or MB with `--si`)
- `-g`, `--gbytes` — GiB (or GB with `--si`)
- `-t`, `--tbytes` — TiB (or TB with `--si`)

### `defragment [options] <file>|<dir> [<file>|<dir>...]`
Defragment file data on a mounted filesystem (requires kernel 2.6.33+).  
**Warning:** On kernels < 3.9, ≥ 3.14‑rc2, and stable 3.10.31/3.12.12/3.13.4, defragmentation breaks reflinks of COW data (snapshots, `cp‑‑reflink`, deduplicated data), possibly increasing space usage.  
Directory arguments **without** `-r` defragment internal metadata trees, not files recursively; use `-r` to defragment files inside directories.  
Units for `start`, `len`, `size`: `K`, `M`, `G`, `T`, `P`, `E` (case‑insensitive).

**Options**
- `-c[<algo>]` — compress file contents while defragmenting; optional algorithm: `zlib` (default), `lzo`, `zstd` (no‑compression not possible)
- `-r` — defragment files recursively in given directories (does not descend to subvolumes/mount points)
- `-f` — flush per‑file data before moving to next file; limits accumulated dirty data
- `-s <start>[kKmMgGtTpPeE]` — start offset (default: 0)
- `-l <len>[kKmMgGtTpPeE]` — length to defragment (default: file size)
- `-t <size>[kKmMgGtTpPeE]` — target extent size; extents larger than this are skipped (default: 32 M, advisory only)
- `-v` — (deprecated) alias for global `-v`

### `du [options] <path> [<path>..]`
Calculate disk usage using FIEMAP. For each file reports total bytes and exclusive (not shared) bytes. For each argument, a **set shared** value is the sum of shared space referenced by files found by recursive search of that argument (descends into subvolumes, not mount points); overlapping shared extents are accounted correctly.

**Options**
- `-s`, `--summarize` — display total per argument only
- `--raw` — raw bytes, no suffix
- `--human-readable` — base 1024 (default)
- `--iec` — 1024 base for following options
- `--si` — 1000 base for following options
- `--kbytes` — KiB (or kB with `--si`)
- `--mbytes` — MiB (or MB with `--si`)
- `--gbytes` — GiB (or GB with `--si`)
- `--tbytes` — TiB (or TB with `--si`)

### `label [<device>|<mountpoint>] [<newlabel>]`
Show or set the filesystem label. Without `newlabel`, the current label is printed. Maximum length < 256 chars, no newline (trailing newline stripped). Works on mounted filesystem or image.

### `resize [options] [<devid>:][+/-]<size>[kKmMgGtTpPeE]|[<devid>:]max <path>`
Resize a mounted filesystem. If `<path>` is a file containing a BTRFS image, it resizes the underlying filesystem, not the image.  
`devid` defaults to 1; find with `btrfs filesystem show`.  
Size may be absolute, relative (`+`/`-`), or `max` to occupy all available space on the device. Shrinking relocates data beyond the new end and can be slow. The underlying partition must be resized separately (e.g. with `fdisk(8)` or `parted(8)`).

**Options**
- `--enqueue` — wait if another exclusive operation is running

### `show [options] [<path>|<uuid>|<device>|<label>]`
Show information about btrfs filesystems. Without arguments, shows all (mounted and unmounted).

**Options**
- `-m`, `--mounted` — probe kernel for mounted filesystems only
- `-d`, `--all-devices` — scan all devices under `/dev` (fallback if no udev)
- `--raw`, `--human-readable`, `--iec`, `--si`, `--kbytes`, `--mbytes`, `--gbytes`, `--tbytes` — unit display (as above)

### `sync <path>`
Force a sync of the filesystem (like `sync(1)`) and start cleaning deleted subvolumes. Use `btrfs subvolume sync` to wait for subvolume deletion to finish.

### `usage [options] <path> [<path>...]`
Show detailed internal filesystem usage. Intended to replace `df`. Root extra detail: block group breakdown by type/profile.  
Summary fields: `Device size`, `Device allocated`, `Device unallocated`, `Device missing`, `Used`, `Free (estimated)` with `min`, `Free (statfs, df)`, `Data ratio`, `Metadata ratio`, `Global reserve`, `Multiple profiles`. On zoned devices: `Device zone unusable`, `Device zone size`.

**Options**
- `-b`, `--raw`
- `-h`, `--human-readable` (default, base 1024)
- `-H` (base 1000)
- `--iec`, `--si`
- `-k`, `--kbytes`; `-m`, `--mbytes`; `-g`, `--gbytes`; `-t`, `--tbytes`
- `-T` — tabular output

## Examples

shell
# Recursively defragment directory, verbose
$ btrfs filesystem defrag -v -r /data

# Defragment with flush per file (reduces IO spikes)
$ btrfs filesystem defrag -v -r -f /data

# Defragment with LZO compression
$ btrfs filesystem defrag -v -r -f -clzo /data

# Defragment, aiming for 64 MiB extents
$ btrfs filesystem defrag -v -r -t 64M /data

# Shrink filesystem on devid 1 by 1 GiB
$ btrfs filesystem resize -1G /mnt
$ btrfs filesystem resize 1:-1G /mnt

# Grow filesystem to maximum device capacity
$ btrfs filesystem resize max /mnt
$ btrfs filesystem resize 1:max /mnt
## Exit Codes
0 on success, non‑zero on failure.

## See Also
- [btrfs‑subvolume(8)](https://man7.org/linux/man-pages/man8/btrfs-subvolume.8.html)
- [mkfs.btrfs(8)](https://man7.org/linux/man-pages/man8/mkfs.btrfs.8.html)