Inspect and Change Btrfs Properties Without Guesswork

You will finish with a repeatable way to list, read and change Btrfs properties on files, directories, subvolumes and filesystems. The examples use btrfs-progs 6.6.3, installed here as package version 6.6.3-1.1build2. Allow about fifteen minutes, plus time to confirm the exact object you intend to change.

You need a Linux shell, btrfs-progs and an existing Btrfs filesystem. Ordinary reads usually need no elevated privileges. Setting a property needs write permission on the target and may need sudo. These commands do not create a filesystem or subvolume. Have a tested backup before changing a production subvolume or filesystem label.

1. Confirm the installed command

Check the binary and version first. This is read-only and normally unprivileged:

$ command -v btrfs
/usr/bin/btrfs
$ btrfs --version
btrfs-progs v6.6.3
$ btrfs property --help

The command group is btrfs property. The shorter spelling btrfs prop is accepted by the installed command and appears in the manual examples, but the full spelling is easier to recognise in a script or runbook.

Checkpoint: if btrfs --version fails, stop here and install btrfs-progs through your normal package-management process. Do not copy a command from a different host and assume its property set is identical.

2. Identify the object and its type

A property can belong to an inode, subvolume, filesystem or device. For the common case of a file or directory, the command can infer the type. Use -t when the object could be interpreted in more than one way:

$ btrfs property list -t inode /mnt/archive/report.txt
$ btrfs property list -t subvol /mnt/archive
$ btrfs property list -t filesystem /mnt/archive

The type names are inode, subvol, filesystem and device. Their one-letter forms are i, s, f and d. A mounted filesystem is represented by its mount point. An unmounted filesystem uses its block-device path for filesystem properties such as its label.

The output is host-specific. Look for the property name and description rather than treating the list as a universal promise. On this release, the documented useful properties are inode compression, subvolume ro and filesystem label.

3. Read properties before changing them

Read every property that applies to an object by omitting the name:

$ btrfs property get /mnt/archive/report.txt
compression=zstd
$ btrfs property get -t subvol /mnt/archive
ro=false

To ask for one value, add its name:

$ btrfs property get /mnt/archive/report.txt compression
compression=zstd
$ btrfs property get -t filesystem /mnt/archive label
label=archive

An empty result can be meaningful. For example, a file with no explicit compression property can inherit the filesystem or directory behaviour. Do not translate an empty output into "compression is disabled" without checking the mount and filesystem configuration separately.

Checkpoint: save the current value before a change. This gives you an exact value to restore, and also catches the common mistake of reading a mount point while intending to inspect a subvolume.

4. Set compression on a file or directory

Compression is an inode property. Set an algorithm on a file or directory with a normal command; use sudo only if the account cannot write the object:

$ btrfs property set /mnt/archive/report.txt compression zstd
$ btrfs property get /mnt/archive/report.txt compression
compression=zstd

The accepted values are lzo, zlib, zstd, no and none. This interface selects the algorithm, not a compression level. Setting no or none disables compression for that inode. Setting an empty value restores the default:

$ btrfs property set /mnt/archive/report.txt compression ''
$ btrfs property get /mnt/archive/report.txt compression

Quote the empty value. Leaving the quotes out changes the argument count and makes the command fail. The empty-value behaviour changed in btrfs-progs 5.18 and requires kernel 5.14 or newer, so check both versions before using it on an older recovery system.

This property does not retroactively rewrite all existing extents in the file. If your aim is to recompress existing data, treat that as a separate operation and plan its I/O and recovery path.

5. Change a subvolume's read-only flag

Read the current flag, then pause before changing it:

$ btrfs property get -t subvol /mnt/snapshots/daily ro
ro=false

$ sudo btrfs property set -t subvol /mnt/snapshots/daily ro true
$ btrfs property get -t subvol /mnt/snapshots/daily ro
ro=true

To undo this example, set the value back to false after confirming that making the subvolume writable is safe:

$ sudo btrfs property set -t subvol /mnt/snapshots/daily ro false
$ btrfs property get -t subvol /mnt/snapshots/daily ro
ro=false

The manual points to subvolume flags for implications around incremental send. Treat read-only snapshots as part of your backup design, not merely as a convenient toggle.

6. Change a filesystem label carefully

The filesystem label property uses a mount point when the filesystem is mounted:

$ btrfs property get -t filesystem /mnt/archive label
label=archive
$ sudo btrfs property set -t filesystem /mnt/archive label cold-storage
$ btrfs property get -t filesystem /mnt/archive label
label=cold-storage

A label is visible to mount and backup tooling, so changing it can break scripts that use the old label. Record dependent configuration before proceeding. To undo the change, set the original label again:

$ sudo btrfs property set -t filesystem /mnt/archive label archive
$ btrfs property get -t filesystem /mnt/archive label
label=archive

For an unmounted filesystem, pass the block-device path instead of a mount point. Do not guess a device name. Resolve it with a read-only command such as findmnt or your documented storage inventory before making a change.

7. Diagnose failures without adding force

A "not a Btrfs filesystem" error usually means the path is on another filesystem, the mount point is wrong, or the device is not the one you intended. Check the path and filesystem type:

$ findmnt -T /mnt/archive -o TARGET,SOURCE,FSTYPE
TARGET       SOURCE        FSTYPE
/mnt/archive /dev/mapper/vg-archive btrfs

If a property is rejected, run btrfs property list for the exact object type and compare the spelling. The -f option exists for changes with additional safety checks, but it can potentially break something. Do not add it just because a normal set failed. First read the error, verify the object, check the current value and consult the relevant Btrfs documentation.

A successful exit status means the property operation succeeded. Always follow a set with btrfs property get. That check proves what the command now reports, while a separate application or filesystem test is needed to prove that the resulting behaviour meets your operational goal.