If you've clicked through Datacenter > Storage > Add in Proxmox VE recently, you've probably noticed a storage type sitting between Directory and ZFS that nobody talks about: BTRFS. There's no walkthrough for it in the GUI, no wizard, and if you go looking under Disks hoping to format a drive with it the way you would with ZFS, you won't find a button for that either. It just... exists, half-finished, waiting for you to set it up by hand.
That's not a bug. BTRFS support in Proxmox VE has been sitting in technology preview since version 7.0, and it's still there in 8.x and 9.x. That scares some people off, and for a production cluster storing customer data, it probably should. But for a homelab, a single-node box, or a second disk you're using for ISO images and container templates, it's a genuinely useful option that a lot of beginners skip simply because nobody explains how to turn it on.
This guide walks through adding a BTRFS-formatted disk as usable storage in Proxmox VE, from a blank drive to something you can pick from the storage dropdown when creating a VM.
What You Will Learn
- What BTRFS actually is, and why Proxmox VE treats it differently from ZFS
- When BTRFS makes sense for your setup, and when it honestly doesn't
- How to wipe and format a spare disk with
mkfs.btrfs - How to mount it correctly and register it with Proxmox VE, both via the GUI and by editing
/etc/pve/storage.cfgdirectly - The one setting that will silently corrupt VM disk images if you skip it
- How to enable compression, and what it actually saves you
What Is This Feature?
BTRFS (usually pronounced "butter-eff-ess" or "better FS") is a copy-on-write filesystem built into the Linux kernel. Copy-on-write means that when you change a file, BTRFS writes the new data to a new location instead of overwriting the old blocks in place. That one design choice is what makes cheap, instant snapshots possible — a snapshot is just a pointer to the state of the filesystem before your changes, and it costs almost nothing to create.
If that sounds familiar, it's because ZFS works on the same basic principle. Proxmox VE has supported ZFS for years and treats it as a first-class citizen, with its own GUI panel for creating pools, checking health, and managing scrubs. BTRFS gets none of that GUI love yet. You get the storage plugin (so Proxmox VE knows how to store VM disks and container root filesystems on it, take snapshots, and do offline migrations), but the filesystem itself has to be created and mounted by hand, outside the web interface.
Two features are worth calling out because they explain most of what makes BTRFS interesting for a Proxmox host: subvolumes and checksums. A subvolume is basically an independent filesystem tree living inside the larger BTRFS filesystem — Proxmox VE puts each VM disk or container into its own subvolume so it can snapshot that one guest without touching anything else. Checksums mean every block of data gets a hash stored alongside it, so BTRFS can tell you (and in RAID1 setups, actually fix) when a block has silently gone bad on disk.
Why Would You Use It?
Honestly, most people running a single boot SSD and a couple of VMs will do fine with the default LVM-Thin storage Proxmox VE sets up during install. You don't need BTRFS to get started. But there are a few situations where it earns its place:
- You want snapshots on plain files, not just qcow2. Directory storage in Proxmox VE only gets snapshot support if your VM disks use the qcow2 format. BTRFS gives you filesystem-level snapshots regardless of the disk image format, and it snapshots container root filesystems too, which qcow2 obviously can't do.
- You want checksums without the RAM overhead of ZFS. ZFS is fantastic, but its ARC cache wants a meaningful chunk of RAM to perform well — figure at least 8 GB free before you even think about it comfortably. BTRFS runs fine on a Raspberry Pi-class board with 2 GB of RAM.
- You're reusing an existing BTRFS drive. Maybe you migrated a disk over from a Synology NAS, an old desktop running BTRFS, or a Steam Deck dock drive, and you'd rather register it as-is than reformat it as ZFS or ext4.
- You want compression on the cheap. BTRFS's built-in
zstdcompression is transparent and genuinely fast. On a directory full of ISO images and LXC templates, it's not unusual to claw back 20-30% of disk space for basically free CPU cost.
Where I'd steer you away from it: don't put your VM boot disks on BTRFS RAID5 or RAID6. The BTRFS project itself still labels those two RAID levels as unstable, and Proxmox's own documentation repeats that warning. If you need parity RAID, use ZFS's RAIDZ instead — it doesn't have this problem.
Prerequisites
Before you start, make sure you have:
- A Proxmox VE 8.x or 9.x host with root (or a user with
Sys.ModifyandDatastore.Allocatepermissions) access to the web interface and shell - A spare, unused disk or partition — a second SSD, a USB drive, or a partition you've already carved out. This guide assumes
/dev/sdb, but checklsblkon your own system before running anything - Around ten minutes, most of which is copying commands and waiting for a quick format
- A backup of anything currently on that disk.
mkfs.btrfswill happily destroy existing data with no confirmation prompt beyond a single warning line
You do not need a subscription of any kind for this. BTRFS storage works identically on the free no-subscription repository and the enterprise one.
Step-by-Step Tutorial
Step 1: Find and confirm your target disk
Open a shell on the Proxmox host (via SSH, or the >_ Shell button in the GUI) and run:
lsblk -o NAME,SIZE,TYPE,MOUNTPOINT,FSTYPELook for the disk you intend to use and confirm it's not mounted anywhere and doesn't hold a partition you actually care about. Getting the device name wrong here is the single most common way people lose data with this guide, so double, then triple check it against the size shown.
Step 2: Wipe old filesystem signatures
If the disk was used before — even for something as simple as a Windows install or an old ext4 partition — clear the old signatures so nothing gets confused later:
wipefs -a /dev/sdbThis removes filesystem and partition table signatures without touching the raw data blocks, which is usually enough to stop the kernel and Proxmox from misdetecting the disk's contents.
Step 3: Format the disk with BTRFS
For a single disk with no redundancy:
mkfs.btrfs -L pve-btrfs -m single -d single /dev/sdbThe -L flag sets a human-readable label (handy later when you're staring at blkid output trying to remember which disk is which). The -m and -d flags set the metadata and data profiles — single means no duplication, which is normal and expected on one disk.
If you have two same-size disks and want mirroring instead, format both together as RAID1:
mkfs.btrfs -L pve-btrfs -m raid1 -d raid1 /dev/sdb /dev/sdcDon't reach for -d raid5 or -d raid6 here. As mentioned above, they're still flagged as experimental and there are documented cases of pool loss on unclean shutdowns. RAID1 or RAID10 are the safe multi-disk options right now.
Step 4: Create a mount point and mount it
mkdir -p /mnt/pve-btrfs
mount /dev/sdb /mnt/pve-btrfsThat mounts it for the current boot only. To make it survive a reboot, grab the disk's UUID and add it to /etc/fstab:
blkid /dev/sdbCopy the UUID="..." value, then add a line like this to /etc/fstab:
UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx /mnt/pve-btrfs btrfs defaults,compress=zstd:1,noatime 0 0The compress=zstd:1 option turns on light, fast compression for every file written from now on (it won't retroactively compress anything already there). noatime stops the kernel from updating "last accessed" timestamps on every read, which is a small but free performance win on any VM storage.
Run mount -a afterward to confirm the fstab line is valid before you reboot and find out the hard way.
Step 5: Register it as storage in Proxmox VE
Now the part that actually has GUI support. Go to Datacenter > Storage > Add > BTRFS. Fill in:
- ID — a short name, e.g.
btrfs-data - Path —
/mnt/pve-btrfs - Content — tick whatever you plan to store here: Disk image, Container, ISO image, Container template, Snippets, Backup
- Nodes — leave on "All" for a single-node setup, or restrict it to the node that physically has the disk in a cluster
There's also an Is Mountpoint checkbox. Turn it on. This tells Proxmox to verify the path is an actual mounted filesystem before writing to it — without it, if the disk ever fails to mount after a reboot, Proxmox will happily write VM disks straight onto your root filesystem's /mnt/pve-btrfs folder instead of erroring out, which fills up your boot drive fast and is a genuinely nasty surprise to debug.
Prefer the command line? The equivalent is a single line in /etc/pve/storage.cfg:
btrfs: btrfs-data
path /mnt/pve-btrfs
content images,rootdir,iso,vztmpl,backup
is_mountpoint 1Save the file (or click Add in the GUI) and the new storage shows up immediately in the left-hand tree, ready to select when you build a VM or container.
Step 6: Set the correct cache mode on any VM disks
This step gets skipped constantly and it's the reason some people conclude "BTRFS is buggy" when the filesystem is working exactly as designed. When you attach a VM disk that lives on BTRFS storage, open the VM's Hardware tab, edit the disk, and set Cache to anything other than Default (No cache) — Write back or Write through both work. BTRFS respects the O_DIRECT flag that "no cache" mode uses, and combining it with BTRFS's own checksumming produces checksum mismatch errors on otherwise perfectly healthy data.
Commands Explained
| Command | What It Does |
|---|---|
lsblk | Lists block devices attached to the system so you can identify the right disk before doing anything destructive to it |
wipefs -a <device> | Erases old filesystem and partition table signatures from a disk |
mkfs.btrfs -m <profile> -d <profile> <device(s)> | Creates a new BTRFS filesystem; the profile controls how metadata (-m) and data (-d) are duplicated or striped across the listed disks |
blkid <device> | Prints the filesystem UUID and type for a device, used to write a stable /etc/fstab entry |
mount -a | Mounts everything listed in /etc/fstab, useful for testing your fstab syntax without rebooting |
btrfs filesystem show | Lists BTRFS filesystems the kernel currently knows about, including which physical devices belong to each one |
btrfs filesystem df <mountpoint> | Shows real space usage broken down by data, metadata, and system chunks — regular df can be misleading on BTRFS because of how chunk allocation works |
btrfs subvolume list <mountpoint> | Lists subvolumes on a BTRFS filesystem, including the per-VM and per-container ones Proxmox creates automatically |
Common Errors
"mkfs.btrfs: ERROR: use the -f option to force overwrite" — BTRFS detected an existing filesystem signature on the disk and is refusing to clobber it without confirmation. Either you skipped Step 2, or wipefs didn't catch everything. Add -f only once you're certain the disk is the right one.
"mount: /mnt/pve-btrfs: wrong fs type, bad option, bad superblock" — usually means the device name in /etc/fstab or your mount command doesn't actually hold a BTRFS filesystem, or you pointed it at the wrong partition (e.g. /dev/sdb instead of /dev/sdb1). Recheck with blkid.
"TASK ERROR: unable to activate storage 'btrfs-data' - directory is expected to be a mount point" — this is the Is Mountpoint safety check doing its job. It means the disk isn't currently mounted at the path Proxmox expects. Run mount -a and check lsblk to confirm the drive is actually connected and mounted before retrying.
Checksum errors in dmesg on a VM that otherwise runs fine — nine times out of ten this is the cache mode issue from Step 6. Fix the disk's cache setting and the errors stop appearing on subsequent writes.
Troubleshooting
If storage shows up in the GUI but every VM creation attempt on it fails, check whether the content types are actually ticked correctly. It's an easy thing to miss — if you only ticked "ISO image" when adding the storage, Proxmox won't let you put a VM disk there, and the error message ("content type images not available on storage") doesn't always make the fix obvious on first read.
If the pool reports itself as read-only after an unclean shutdown, run:
btrfs check /dev/sdbon the unmounted device (you'll need to unmount it first) to scan for filesystem errors. Don't run btrfs check --repair as a first move — it's a more invasive operation than the ZFS or ext4 equivalents and has, in rare cases, made things worse on already-damaged filesystems. Back up what you can reach first.
Space reporting that doesn't match what you expect is normal, not a bug. BTRFS allocates space in large chunks ahead of actually needing it, so df -h can show less free space than you think you should have. btrfs filesystem df gives you the real breakdown.
Best Practices
- Stick to RAID0, RAID1, or RAID10 profiles. Skip RAID5/RAID6 entirely until upstream BTRFS marks them stable — that hasn't happened yet as of this writing.
- Always tick Is Mountpoint when adding the storage. It costs nothing and prevents the "silently writing to root disk" failure mode described above.
- Set VM disk cache to Write back or Write through, never the default "No cache," on any disk backed by BTRFS.
- Run
btrfs scrub start /mnt/pve-btrfsoccasionally (monthly is reasonable for a homelab) to have BTRFS proactively verify checksums and catch silent corruption before it becomes a real problem. On RAID1 it can even self-heal a bad copy using the good one. - Keep this storage type off anything you'd call "production" until Proxmox drops the technology preview label. Enterprise deployments should stick with ZFS or Ceph for now.
Frequently Asked Questions
Is BTRFS storage stable enough to trust with real data?
For a homelab, most people find it stable in day-to-day use. It's the "technology preview" label from Proxmox, not upstream instability, that keeps it out of production recommendations — the underlying filesystem itself has been shipping in mainstream Linux distributions for over a decade.
Can I convert my existing ZFS or LVM-Thin storage to BTRFS?
No, not in place. You'd need to move VM disks off the old storage (backup and restore, or storage migration to another pool), reformat the disk as BTRFS, then move the disks back onto the new storage.
Does BTRFS support thin provisioning like LVM-Thin or ZFS?
Yes. VM disks stored as raw files on BTRFS only consume the space actually written to them, same as on any copy-on-write filesystem.
Why isn't there a "Disks > BTRFS" tab like there is for ZFS?
Proxmox's developers have said fuller GUI integration is planned but haven't committed to a timeline. For now, filesystem creation stays a manual, shell-based step even though the storage plugin itself is GUI-manageable.
Can I use BTRFS for my Proxmox VE boot/root disk?
Yes — the installer offers it as a root filesystem option with RAID0, RAID1, or RAID10, separate from adding it as extra VM storage after the fact, which is what this guide covers.
Conclusion
BTRFS on Proxmox VE is a strange in-between feature right now: fully functional as a storage backend, snapshot-capable, and genuinely lighter on resources than ZFS, but still missing the GUI polish that makes ZFS approachable for beginners. Once you've formatted the disk and mounted it correctly, though, Proxmox treats it just like any other storage pool — you pick it from a dropdown and forget about it.
If you've been putting off trying it because the lack of a wizard made it look unsupported, it isn't. It just wants ten minutes at the shell first.