Skip to content

This document is a WORK IN PROGRESS.
This is just a quick personal cheat sheet: treat its contents with caution!


Btrfs CoW file system for Linux aimed at implementing advanced features while focusing on fault tolerance, repair, and easy administration.


Table of contents


A correct kernel config is needed:

$ cd /usr/src/linux
# make nconfig # or `# make menuconfig`

    # Activate Btrfs in the kernel
    # Double check here: <>
    > File systems  --->
    >     <*> Btrfs filesystem support # Symbol: BTRFS_FS [=y]


After configuring the kernel don't forget to do a kernel make and rebuild!

# emerge -a sys-fs/btrfs-progs
# pacman -S btrfs-progs
# apt install btrfs-progs
# yum install btrfs-progs
# dnf install btrfs-progs


/dev/sdXN will be the disk partition to format ("X" the disk number, "N" the partition letter)

Create OR convert a FS to a "simple" Btrfs

  • Create a Btrfs file system on the /dev/sdXN partition :
    # mkfs.btrfs /dev/sdXN # mkfs.btrfs irreversibly destroys any content of the formated partition


  • Convert a whole disk ext4 based file system to Btrfs file system:
    # umount /dev/sdX
    # fsck.ext4 -f /dev/sdX # Check the integrity of the filesystem using the appropriate fsck tool
    # btrfs-convert /dev/sdX # Use btrfs-convert to convert the ext* formatted device into a Btrfs-formatted device

Create a FS to RAID 1 Btrfs

  • Create a Btrfs file system on the /dev/sdX and /dev/sdY disks:
    # mkfs.btrfs -m raid1 /dev/sdX /dev/sdY -d raid1 /dev/sdX /dev/sdY # -m for metadata and -d for data

Add an fstab entry

  • Configure fstab to mount Btrfs disks (e.g. with zstd compression, other options are zlib or lzo):
    # sudo vi /etc/fstab
        > ...
        > UUID=...   /dev/sdX  btrfs  defaults,noatime,compress=zstd  0 0
        > ...


  • Global usage:

  • Re compress the whole file system (e.g. with zstd compression method):

    # btrfs filesystem defragment -r -v -czstd /path-to-mount-point/mount-point

  • Report file space usage with Btrfs:

    # btrfs filesystem du -s /media/drive

  • Report disk space usage with Btrfs:

    # btrfs filesystem df /media/drive

  • Report full breakdown of device allocation and usage stats:

    # btrfs filesystem usage /media/raid



Turning off CoW also turns off checksums which puts your data "at risk" (as much as with ext4). Without checksums, Btrfs can't self heal from disk corruptions (even on RAID1 setups). See



A scrub is an online file system checking tool. Reads all the data and metadata on the file system, and uses checksums and the duplicate copies from RAID storage to identify and repair any corrupt data.

  • Start a (background) scrub:

    # btrfs scrub start /media/drive

  • Check the status of a running scrub:

    # btrfs scrub status /media/drive

Sub volumes


Commit interval

If this cheat sheet has been useful to you, then please consider leaving a star here.