btrfstune - Linux


btrfstune is a utility for tuning Btrfs filesystems. It allows administrators to adjust various parameters to optimize performance, reliability, and storage characteristics.


btrfstune [-d] [-f] [-l] [-o <parameters>] [-r] [-s] <device>


  • -d: Disable tuning.
  • -f: Force tuning even if the filesystem is mounted.
  • -l: List current tuning parameters.
  • -o : Set tuning parameters (see below).
  • -r: Revert to default tuning parameters.
  • -s: Show tuning parameters in human-readable format.

Tuning Parameters

The following parameters can be set using the -o option:

  • devicegroup-split-per-thread: Number of threads to split device groups across.
  • devices: Priority list of devices for the filesystem.
  • disable-nocow-checksum: Disable checksumming for nocow metadata updates.
  • enable-qgroup: Enable quota groups.
  • metadata-blocksize: Size of metadata blocks.
  • mirror-uuid: Mirror UUID to use for RAID1 mirrors.
  • raid5-stripe: Number of data stripes in RAID5 arrays.
  • raid6-stripe: Number of data stripes in RAID6 arrays.
  • reserve-data: Percentage of data space to reserve for metadata.
  • reserve-metadata: Percentage of metadata space to reserve for snapshots.
  • rotation-max-delay: Maximum rotation delay for mirror writes.
  • rotation-rate: Rotation rate for mirror writes.
  • ssd: Mark the device as an SSD.


  1. List current tuning parameters:
btrfstune -l /dev/sdc2
  1. Disable tuning:
btrfstune -d /dev/sdc2
  1. Set the metadata block size to 16k:
btrfstune -o metadata-blocksize=16k /dev/sdc2
  1. Set the device group split-per-thread parameter to 2:
btrfstune -o devicegroup-split-per-thread=2 /dev/sdc2

Common Issues

  • Filesystem is mounted: Use the -f flag to force tuning on a mounted filesystem.
  • Invalid tuning parameter: Ensure the specified parameter and value are valid.
  • Filesystem compatibility: Some tuning parameters may not be compatible with all filesystem versions.


  • btrfs-progs: btrfstune is part of the btrfs-progs package.
  • Scripts: btrfstune can be incorporated into scripts to automate filesystem tuning tasks.

Related Commands

  • mkfs.btrfs: Create a Btrfs filesystem.
  • btrfs: Manage and manipulate Btrfs filesystems.
  • btrfs-inspect: Analyze and inspect Btrfs filesystems.