# info > BTRFS-QGROUP

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

## Quick Reference
- `btrfs qgroup create 1/100 <path>` — Create a new qgroup
- `btrfs qgroup assign 0/261 1/100 <path>` — Make 0/261 a child of 1/100
- `btrfs qgroup limit 10M 1/100 <path>` — Set a 10 MiB limit on qgroup
- `btrfs qgroup limit none <qgroupid> <path>` — Remove the size limit
- `btrfs qgroup show <path>` — Show all qgroups with basic stats
- `btrfs qgroup show -prFe --raw <path>` — Detailed listing with parent/child relations, exclusive limits, and raw bytes
- `btrfs qgroup remove 0/261 1/100 <path>` — Remove child-parent relationship
- `btrfs qgroup destroy 0/261 <path>` — Delete a qgroup (must not be in a relationship)

## Name
`btrfs-qgroup` — control the quota group of a btrfs filesystem

## Synopsis
shell
btrfs qgroup <subcommand> <args>
**Note:** Quota must first be enabled with `btrfs quota enable`. Qgroups are not stable and may cause performance impact (mainline kernel v4.14+).

## Options
### `assign` — set parent-child relationship
- `--rescan` — Automatically schedule quota rescan (default since 4.19).
- `--no-rescan` — Skip rescan even if it leads to inconsistency.

### `create <qgroupid> <path>` — create a new qgroup
No extra options. For qgroup `0/<subvolid>`, can be created before the subvolume exists.

### `destroy <qgroupid> <path>` — delete a qgroup
The qgroup must not be a parent or child in any relationship.

### `limit [options] <size>|none [<qgroupid>] <path>` — set or clear a size limit
- `-c` — (default) limit amount of data after compression. Only effective behaviour; cannot be turned off.
- `-e` — limit space exclusively assigned to this qgroup.
- Size can be a number with suffix (K, M, G, T) or `none` to remove the limit.

### `remove <src> <dst> <path>` — remove a child-parent relation
- `--rescan` — (default since 4.19) schedule rescan if needed.
- `--no-rescan` — skip rescan.

### `show [options] <path>` — display all qgroups
- `-p` — print parent qgroup id.
- `-c` — print child qgroup id.
- `-r` — print referenced size limit.
- `-e` — print exclusive size limit.
- `-F` — list all qgroups that impact the given path (including ancestors).
- `-f` — list all qgroups that impact the given path (excluding ancestors).
- `--raw` — raw numbers in bytes.
- `--human-readable` — friendly units (default, base 1024).
- `--iec` / `--si` — select 1024 (IEC) or 1000 (SI) base for size formatting.
- `--kbytes`, `--mbytes`, `--gbytes`, `--tbytes` — override unit display.
- `--sort=[+/-]<attr>[,[+/-]<attr>]...` — sort by `qgroupid`, `rfer`, `excl`, `max_rfer`, `max_excl`. Prefix `+` ascending (default), `-` descending.
- `--sync` — sync filesystem before reporting to get up‑to‑date qgroup state.

### Rescan behaviour
When qgroup relationships change, extent ownership changes can make qgroup numbers inconsistent. A full rescan reads all extent sharing metadata to correct this. If a subvolume's exclusive bytes equal its referenced bytes, only a simple add/subtract from the parent is needed, avoiding a full rescan.

## Examples
Enable quota, create subvolumes, set up a parent qgroup with two children and a 10 MiB limit:

shell
cd /mnt/my-vault
btrfs quota enable .
btrfs subvolume create a
btrfs subvolume create b
btrfs subvolume list .
# ID 261 gen 61 top level 5 path a
# ID 262 gen 62 top level 5 path b

btrfs qgroup create 1/100 .
btrfs qgroup limit 10M 1/100 .
btrfs qgroup assign 0/261 1/100 .
btrfs qgroup assign 0/262 1/100 .

btrfs qgroup show .
# qgroupid         rfer         excl
# --------         ----         ----
# 0/5          16.00KiB     16.00KiB
# 0/261        16.00KiB     16.00KiB
# 0/262        16.00KiB     16.00KiB
# 1/100        32.00KiB     32.00KiB
## See Also
- [mkfs.btrfs(8)](http://localhost/phpMan.php/man/mkfs.btrfs/8/markdown)
- [btrfs-subvolume(8)](http://localhost/phpMan.php/man/btrfs-subvolume/8/markdown)
- [btrfs-quota(8)](http://localhost/phpMan.php/man/btrfs-quota/8/markdown)

## Exit Codes
- **0** — success
- **non‑zero** — failure