Change Btrfs Features and UUIDs Safely with btrfstune

Run btrfstune on the wrong device, or in the wrong order, and you can turn a healthy Btrfs filesystem into one that will not mount. This guide gets you through one deliberate feature or UUID change on an unmounted device, then verifies it before you mount again. Allow 15 to 30 minutes for a feature toggle, longer for a full UUID rewrite.

It describes the locally installed btrfstune from btrfs-progs 6.6.3 and its installed btrfstune(8) page. The examples use a placeholder device; replace it only after checking the path.

• The filesystem must be unmounted. No exceptions.
• The command writes metadata. A current backup and a tested recovery route are prerequisites, not optional housekeeping.

1. Check the tool and identify the device

Run the discovery commands as your ordinary account. Do not start with sudo btrfstune: first establish exactly which block device holds the filesystem you mean to change.

$ command -v btrfstune
/usr/bin/btrfstune
$ dpkg-query -W -f='${Package} ${Version}\n' btrfs-progs
btrfs-progs 6.6.3-1.1build2
$ lsblk -o NAME,PATH,FSTYPE,LABEL,UUID,MOUNTPOINTS
$ findmnt -t btrfs

The output of lsblk and findmnt is host-specific. A Btrfs filesystem can span several devices, so do not assume the device mounted at a familiar directory is the only member. For a multi-device filesystem, plan around the filesystem and all of its devices, and keep the device names you recorded before unmounting.

Checkpoint: you have written down the exact device path, current filesystem UUID, mountpoint and whether other devices belong to the same filesystem. If you cannot account for those items, stop here.

2. Inspect the available operations

Compare the local help with the local manpage before choosing an option:

$ btrfstune --help
$ man btrfstune

The installed manpage documents these operations:

• Feature toggles. Extended inode references (-r), skinny metadata extent references (-x), no-holes (-n), block-group-tree conversion, free-space-tree conversion and seeding.
• Metadata-only UUID changes. -m and -M.
• Full UUID rewrites. -u and -U.

Warning: there is a version boundary here. This machine's 6.6.3 executable advertises -q for simple quotas, but the installed manpage does not document it. Do not put that option into a script based only on this article. Use the help and documentation shipped with the exact package on the target host, and confirm the kernel supports the feature.

3. Unmount the filesystem and confirm the boundary

Stopping access is the first privileged step. Schedule a maintenance window if services, containers or users depend on the filesystem. Replace /srv/data with the actual mountpoint.

$ sudo fuser -vm /srv/data
$ sudo umount /srv/data
$ findmnt /srv/data
target is not mounted

The final command should print no mount record. If umount reports that the target is busy, find the process or service holding it open, stop that service cleanly, then retry.

Tip: do not reach for lazy unmounting as a shortcut. It can leave processes using the filesystem while you are trying to change its metadata.

Warning: the following commands change filesystem metadata. A wrong device can damage an unrelated filesystem, and a failed or interrupted UUID operation can temporarily make the filesystem unmountable.

4. Enable one documented feature

Choose one operation, not a bag of flags. For example, this enables the no-holes feature on a device:

$ sudo btrfstune -n /dev/mapper/PLACEHOLDER_BTRFS
$ printf 'exit status: %s\n' "$?"
exit status: 0

A zero status means btrfstune reported no error. It does not mean every kernel in your fleet can mount the result. The locally documented no-holes, extref and skinny-metadata operations need kernel support, with the manpage listing minimum kernel versions 3.14, 3.7 and 3.10 respectively.

The conversion operations have their own limits:

• Block-group-tree conversion needs kernel 6.1 or newer.
• Free-space-tree conversion needs kernel 4.5 or newer.

Use the exact long option from the manpage, for example:

$ sudo btrfstune --convert-to-free-space-tree /dev/mapper/PLACEHOLDER_BTRFS

Tip: do not run a conversion merely to make a filesystem look modern. Check the kernel versions of every system that may mount it, including rescue media and older hosts.

5. Treat UUID changes as a separate change window

-m and -M change the metadata UUID in the superblock without rewriting every metadata block. The full operations -u and -U rewrite the filesystem UUID throughout the metadata and can take much longer.

For a deliberate full change to a known UUID, use the documented 36-character form:

$ sudo btrfstune -U 01234567-89ab-cdef-0123-456789abcdef /dev/mapper/PLACEHOLDER_BTRFS

The new UUID must be unique in the systems that will discover this filesystem. Update any inventory or mount configuration that refers to the old UUID only after the operation succeeds. For a randomly generated full UUID, use -u instead.

Recovery: for an interrupted full UUID change, rerun -u and let it complete. The manpage specifically warns that interrupting this operation can leave the filesystem temporarily unmountable.

Warning: do not use -f as a general-purpose retry switch. It permits dangerous changes such as clearing the seeding flag or changing the fsid. Clearing seeding can make filesystems built from that seed unmountable, and setting the flag back does not repair that damage.

6. Verify before remounting

Record the exit status and inspect the filesystem identity before bringing services back. These are ordinary commands, although reading a block device may need elevated privileges on your host:

$ printf 'btrfstune status: %s\n' "$?"
btrfstune status: 0
$ sudo blkid /dev/mapper/PLACEHOLDER_BTRFS
/dev/mapper/PLACEHOLDER_BTRFS: UUID="..." TYPE="btrfs"
$ sudo btrfs filesystem show /dev/mapper/PLACEHOLDER_BTRFS

UUID formatting and the device list vary. Confirm three things:

• The type is Btrfs.
• The UUID is right. It is the intended new value, or unchanged if you did not touch it.
• Every expected member is present.

If the command failed, keep the filesystem unmounted and preserve the error output. Do not stack another tuning operation on top of it.

Recovery: when a full UUID change was interrupted, the manpage's recovery action is sudo btrfstune -u DEVICE. Let it finish without cancellation. If the filesystem will not open or the device reports I/O errors, stop and use your backup and Btrfs recovery procedure rather than improvising with repair commands.

7. Mount and restore service

Only remount after the metadata checks pass. Use the normal mount configuration rather than inventing new options:

$ sudo mount /srv/data
$ findmnt -t btrfs /srv/data
$ sudo systemctl start YOUR_SERVICE

Replace YOUR_SERVICE with the service you stopped, or omit that line when the mount is not service-managed. Check that the expected files are present and that the service's health check succeeds.

Recovery: if the mount fails after a feature change, do not keep retrying across different kernels. Use a compatible rescue environment and the pre-change details you recorded.

Done means

• Version checked. You verified the installed btrfs-progs version and chose an option documented for the target host.
• Right device. You recorded the device, filesystem identity and all members of any multi-device filesystem.
• Unmounted first. The filesystem was unmounted before metadata was changed.
• One change only. You made one planned feature or UUID change and kept its exit status.
• Verified. You checked the Btrfs type, UUID and device list before remounting.
• Recovery ready. You have a path for an interrupted UUID rewrite and did not use -f casually.