btrfs-subvolume

Create a new empty subvolume

$ sudo btrfs [[su|subvolume]] [[c|create]] [path/to/new_subvolume]

$ sudo btrfs [[su|subvolume]] [[l|list]] [path/to/btrfs_filesystem]

$ sudo btrfs [[su|subvolume]] [[d|delete]] [path/to/subvolume]

$ sudo btrfs [[su|subvolume]] [[sn|snapshot]] -r [path/to/source_subvolume] [path/to/target]

$ sudo btrfs [[su|subvolume]] [[sn|snapshot]] [path/to/source_subvolume] [path/to/target]

$ sudo btrfs [[su|subvolume]] [[sh|show]] [path/to/subvolume]

btrfs subvolume {create|delete|list|snapshot|sync|show|get-default|set-default} [options] ...

create
    Create a new writable subvolume at <dest>

delete
    Delete the subvolume(s) at <path>

list
    List subvolumes in <path>

snapshot
    Create a snapshot of <source> at <dest>

sync
    Wait for all subvolume changes at <path> to flush

show
    Show detailed info for subvolume at <path>

get-default
    Get the default subvolume for <path>

set-default
    Set default subvolume ID or path for <path>

-r
    Create readonly snapshot (snapshot subcommand)

-p <parent>
    Set parent subvolume for newly created subvolume/snapshot

-u <uuid>
    Set UUID for new subvolume/snapshot

-i <inode>
    Use inode from <source> for new subvolume/snapshot

-c
    Commit after deleting last subvolume (delete); show generation counters (list)

-a
    List all subvolumes, including empty (list)

-d
    List only default subvolume path (list)

-R
    List recursively (list)

-q
    Quiet mode, suppress errors

The btrfs subvolume command manages subvolumes and snapshots in a BTRFS filesystem. BTRFS subvolumes act as separate mountable units within the filesystem, enabling efficient space sharing, copy-on-write snapshots for backups, and versioning without full data duplication.

Key features include creating writable subvolumes or read-only snapshots, deleting subvolumes, listing them with details like UUIDs or usage, setting mount defaults, and syncing pending changes. Snapshots capture filesystem state instantly, ideal for rollbacks or testing.

This tool leverages BTRFS's advanced capabilities for data integrity (checksums, copy-on-write), compression, and quotas. It's crucial for servers, containers, and backups, but requires unmounted subvolumes for some operations. Use with btrfs filesystem for quotas and mount for independent mounting.

Operations are atomic where possible, but always verify with btrfs subvolume list and check space usage to avoid issues.

Subvolumes/snapshots must be unmounted before delete; shared extents mean deletion doesn't free space immediately; root subvolume deletion risks filesystem; snapshots consume space on writes only.

btrfs subvolume create /mnt/@home
btrfs subvolume snapshot /mnt/@ /mnt/@backup
btrfs subvolume list /mnt

Part of btrfs-progs since BTRFS inception (~2007 by Oracle/Chris Mason); subvolume support in kernel 2.6.29+; enhanced snapshots/defaults in 3.x kernels; widely used in Fedora, openSUSE.

btrfs(8), btrfs-filesystem(8), mkfs.btrfs(8), mount(8)