Convert your filesystem to Btrfs

Introduction

The purpose of this article is to give you an overview about why, and how to migrate your current partitions to a Btrfs filesystem. To read a step-by-step walk through of how this is accomplished – follow along, if you’re curious about doing this yourself.

Starting with Fedora 33, the default filesystem is now Btrfs for new installations. I’m pretty sure that most users have heard about its advantages by now: copy-on-write, built-in checksums, flexible compression options, easy snapshotting and rollback methods. It’s really a modern filesystem that brings new features to desktop storage.

Updating to Fedora 33, I wanted to take advantage of Btrfs, but personally didn’t want to reinstall the whole system for ‘just a filesystem change’. I found [there was] little guidance on how exactly to do it, so decided to share my detailed experience here.

Watch out!

Doing this, you are playing with fire. Hopefully you are not surprised to read the following:

During editing partitions and converting file systems, you can have your data corrupted and/or lost. You can end up with an unbootable system and might be facing data recovery. You can inadvertently delete your partitions or otherwise harm your system.

These conversion procedures are meant to be safe even for production systems – but only if you plan ahead, have backups for critical data and rollback plans. As a sudoer, you can do anything without limits, without any of the usual safety guards protecting you.

The safe way: reinstalling Fedora

Reinstalling your operating system is the ‘official’ way of converting to Btrfs, recommended for most users. Therefore, choose this option if you are unsure about anything in this guide. The steps are roughly the following:

  1. Backup your home folder and any data that might be used in your system like /etc. [Editors note: VM’s too]
  2. Save your list of installed packages to a file.
  3. Reinstall Fedora by removing your current partitions and choosing the new default partitioning scheme with Btrfs.
  4. Restore the contents of your home folder and reinstall the packages using the package list.

For detailed steps and commands, see this comment by a community user at ask.fedoraproject.org. If you do this properly, you’ll end up with a system that is functioning in the same way as before, with minimal risk of losing any data.

Pros and cons of conversion

Let’s clarify this real quick: what kind of advantages and disadvantages does this kind of filesystem conversion have?

The good

  • Of course, no reinstallation is needed! Every file on your system will remain the exact same as before.
  • It’s technically possible to do it in-place i.e. without a backup.
  • You’ll surely learn a lot about btrfs!
  • It’s a rather quick procedure if everything goes according to plan.

The bad

  • You have to know your way around the terminal and shell commands.
  • You can lose data, see above.
  • If anything goes wrong, you are on your own to fix it.

The ugly

  • You’ll need about 20% of free disk space for a successful conversion. But for the complete backup & reinstall scenario, you might need even more.
  • You can customize everything about your partitions during the process, but you can also do that from Anaconda if you choose to reinstall.

What about LVM?

LVM layouts have been the default during the last few Fedora installations. If you have an LVM partition layout with multiple partitions e.g. / and /home, you would somehow have to merge them in order to enjoy all the benefits of Btrfs.

If you choose so, you can individually convert partitions to Btrfs while keeping the volume group. Nevertheless, one of the advantages of migrating to Btrfs is to get rid of the limits imposed by the LVM partition layout. You can also use the send-receive functionality offered by btrfs to merge the partitions after the conversion.

See also on Fedora Magazine: Reclaim hard-drive space with LVM, Recover your files from Btrfs snapshots and Choose between Btrfs and LVM-ext4.

Getting acquainted with Btrfs

It’s advisable to read at least the following to have a basic understanding about what Btrfs is about. If you are unsure, just choose the safe way of reinstalling Fedora.

Must reads

Useful resources

Conversion steps

Create a live image

Since you can’t convert mounted filesystems, we’ll be working from a Fedora live image. Install Fedora Media Writer and ‘burn’ Fedora 33 to your favorite USB stick.

Free up disk space

btrfs-convert will recreate filesystem metadata in your partition’s free disk space, while keeping all existing ext4 data at its current location.

Unfortunately, the amount of free space required cannot be known ahead – the conversion will just fail (and do no harm) if you don’t have enough. Here are some useful ideas for freeing up space:

  • Use baobab to identify large files & folders to remove. Don’t manually delete files outside of your home folder if possible.
  • Clean up old system journals: journalctl –vacuum-size=100M
  • If you are using Docker, carefully use tools like docker volume prune, docker image prune -a
  • Clean up unused virtual machine images inside e.g. GNOME Boxes
  • Clean up unused packages and flatpaks: dnf autoremove, flatpak remove –unused,
  • Clean up package caches: pkcon refresh force -c -1, dnf clean all
  • If you’re confident enough to, you can cautiously clean up the ~/.cache folder.

Convert to Btrfs

Save all your valuable data to a backup, make sure your system is fully updated, then reboot into the live image. Run gnome-disks to find out your device handle e.g. /dev/sda1 (it can look different if you are using LVM). Check the filesystem and do the conversion: [Editors note: The following commands are run as root, use caution!]

$ sudo su -
# fsck.ext4 -fyv /dev/sdXX
# man btrfs-convert (read it!)
# btrfs-convert /dev/sdXX

This can take anywhere from 10 minutes to even hours, depending on the partition size and whether you have a rotational or solid-state hard drive. If you see errors, you’ll likely need more free space. As a last resort, you could try btrfs-convert -n.

How to roll back?

If the conversion fails for some reason, your partition will remain ext4 or whatever it was before. If you wish to roll back after a successful conversion, it’s as simple as

# btrfs-convert -r /dev/sdXX

Warning! You will permanently lose your ability to roll back if you do any of these: defragmentation, balancing or deleting the ext2_saved subvolume.

Due to the copy-on-write nature of Btrfs, you can otherwise safely copy, move and even delete files, create subvolumes, because ext2_saved keeps referencing to the old data.

Mount & check

Now the partition is supposed to have btrfs file system. Mount it and look around your files… and subvolumes!

# mount /dev/sdXX /mnt
# man btrfs-subvolume (read it!)
# btrfs subvolume list / (-t for a table view)

Because you have already read the relevant manual page, you should now know that it’s safe to create subvolume snapshots, and that you have an ext2-saved subvolume as a handy backup of your previous data.

It’s time to read the Btrfs sysadmin guide, so that you won’t confuse subvolumes with regular folders.

Create subvolumes

We would like to achieve a ‘flat’ subvolume layout, which is the same as what Anaconda creates by default:

toplevel (volume root directory, not to be mounted by default)
  +-- root (subvolume root directory, to be mounted at /)
  +-- home (subvolume root directory, to be mounted at /home)

You can skip this step, or decide to aim for a different layout. The advantage of this particular structure is that you can easily create snapshots of /home, and have different compression or mount options for each subvolume.

# cd /mnt
# btrfs subvolume snapshot ./ ./root2
# btrfs subvolume create home2
# cp -a home/* home2/

Here, we have created two subvolumes. root2 is a full snapshot of the partition, while home2 starts as an empty subvolume and we copy the contents inside. (This cp command doesn’t duplicate data so it is going to be fast.)

  • In /mnt (the top-level subvolume) delete everything except root2, home2, and ext2_saved.
  • Rename root2 and home2 subvolumes to root and home.
  • Inside root subvolume, empty out the home folder, so that we can mount the home subvolume there later.

It’s simple if you get everything right!

Modify fstab

In order to mount the new volume after a reboot, fstab has to be modified, by replacing the old ext4 mount lines with new ones.

You can use the command blkid to learn your partition’s UUID.

UUID=xx / btrfs subvol=root 0 0
UUID=xx /home btrfs subvol=home 0 0

(Note that the two UUIDs are the same if they are referring to the same partition.)

These are the defaults for new Fedora 33 installations. In fstab you can also choose to customize compression and add options like noatime.

See the relevant wiki page about compression and man 5 btrfs for all relevant options.

Chroot into your system

If you’ve ever done system recovery, I’m pretty sure you know these commands. Here, we get a shell prompt that is essentially inside your system, with network access.

First, we have to remount the root subvolume to /mnt, then mount the /boot and /boot/efi partitions (these can be different depending on your filesystem layout):

# umount /mnt
# mount -o subvol=root /dev/sdXX /mnt
# mount /dev/sdXX /mnt/boot
# mount /dev/sdXX /mnt/boot/efi

Then we can move on to mounting system devices:

# mount -t proc /proc /mnt/proc
# mount --rbind /dev /mnt/dev
# mount --make-rslave /mnt/dev
# mount --rbind /sys /mnt/sys
# mount --make-rslave /mnt/sys
# cp /mnt/etc/resolv.conf /mnt/etc/resolv.conf.chroot
# cp -L /etc/resolv.conf /mnt/etc
# chroot /mnt /bin/bash
$ ping www.fedoraproject.org

Reinstall GRUB & kernel

The easiest way – now that we have network access – is to reinstall GRUB and the kernel because it does all configuration necessary. So, inside the chroot:

# mount /boot/efi
# dnf reinstall grub2-efi shim
# grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg
# dnf reinstall kernel-core
...or just renegenerating initramfs:
# dracut --kver $(uname -r) --force

This applies if you have an UEFI system. Check the docs below if you have a BIOS system. Let’s check if everything went well, before rebooting:

# cat /boot/grub2/grubenv
# cat /boot/efi/EFI/fedora/grub.cfg
# lsinitrd /boot/initramfs-$(uname -r).img | grep btrfs

You should have proper partition UUIDs or references in grubenv and grub.cfg (grubenv may not have been updated, edit it if needed) and see insmod btrfs in grub.cfg and btrfs module in your initramfs image.

See also: Reinstalling GRUB 2 and Verifying the Initial RAM Disk Image in the Fedora System Administration Guide.

Reboot

Now your system should boot properly. If not, don’t panic, go back to the live image and fix the issue. In the worst case, you can just reinstall Fedora from right there.

After first boot

Check that everything is fine with your new Btrfs system. If you are happy, you’ll need to reclaim the space used by the old ext4 snapshot, defragment and balance the subvolumes. The latter two might take some time and is quite resource intensive.

You have to mount the top level subvolume for this:

# mount /dev/sdXX -o subvol=/ /mnt/someFolder
# btrfs subvolume delete /mnt/someFolder/ext2_saved

Then, run these commands when the machine has some idle time:

# btrfs filesystem defrag -v -r -f /
# btrfs filesystem defrag -v -r -f /home
# btrfs balance start -m /

Finally, there’s a “no copy-on-write” attribute that is automatically set for virtual machine image folders for new installations. Set it if you are using VMs:

#

chattr +C /var/lib/libvirt/images
$ chattr +C
~/.local/share/gnome-boxes/images

This attribute only takes effect for new files in these folders. Duplicate the images and delete the originals. You can confirm the result with lsattr.

Wrapping up

I really hope that you have found this guide to be useful, and was able to make a careful and educated decision about whether or not to convert to Btrfs on your system. I wish you a successful conversion process!

Feel free to share your experience here in the comments, or if you run into deeper issues, on ask.fedoraproject.org.

FAQs and Guides For System Administrators

26 Comments

  1. Hugo Lopes

    Portuguese –>> Existe algum script ou programa que já faça isso tudo de forma automática, iguais as facilidades do Windows (por isso eles chegaram onde chegaram), ou se tem que fazer tudo na mão (sem formatar, obvio) comando por comando (o que é chato). Caso não se tenha um script ou programa assim, fica a dica, inclusive para todos os formatos (ext2, ext4, etc).

    • Taniguchi

      Seguinte… não existe script.. e tbm não recomendo esse tipo de procedimento. Pois há muitas chances de não dar certo! É mais seguro vc fazer backup de tudo, e partir para uma nova instalação do SO. Eu sempre usei EXT4, mas agora estou com o Btrfs. Fiz a conversão dele através de uma instalação limpa, do zero. Não tive problemas até agora!

  2. AndreaS

    Nice guide, I think I will try it. One question. I am currently running Fedora 33 on an external disk on my laptop.
    Any chance that after conversion I will still be able to boot Fedora from the external Disk?

    • Hi, you will be able to boot the same, because likely there is no difference between an internal and an external drive from the computer’s perspective.
      In this guide, we don’t touch /boot, only reinstall GRUB to accommodate the filesystem changes.

  3. Thanks Gergely for this introduction to Btrfs convertion.

    I’m new to Fedora and partitioned my system like the old days on Debian . It’s working fine for me to have /, /boot and /home separated but on the same ext4 partition scheme. I don’t know if its a good idea to convert into Btrfs for everyday desktop usage but it may have some advantages over the sever or cloud platforms. Let’s not rush through this and see what happens during next few month or even years!

    P.S: I now understand why Fedora is such a great community for new technologies 😉

    • Hi! Btrfs is mature and totally safe for desktop usage. It’s way beyond early testing phases. That’s why it has been selected as the default file system for Fedora Workstation.
      Of course, deciding whether to convert your FS is up to you, I hope this article gave some useful pointers on why it might be worth it.

      • Karol

        Well.. Good luck. Two months ago my OpenSuse TW had a total FS disaster (/home unfortunately) after just maybe 1 year after installation. Guess what was the filesystem? Yes, it was btrfs. This is the only total FS crash I can remember, and I have been using Linux since 1998.

  4. svsv sarma

    This reminds me of the ‘Fat -NTFS’ conversion. Change always invites alertness, caution and guard and takes its own time to sink in. I decided to install Fedora 34 only, whether it retains ButterFS or not.

  5. Tomasz

    Eh..

    Convert to a self healing system that runs on top of raid 6 to assist with drive failure and then see your data go after a power loss when one system tries to correct the other and kernel panicking every 5 or so minutes when btrfs says the error is unrecoverable.

    After desperately trying to recover 4tb of memories (photos and videos) and important archives and recognizing there are no tools to help me out during the 5 minute session between reboots I will never go back to btrfs.

    YMMV.

  6. Amir

    Can I do the filesystem change while on dual boot with Windows 10?

  7. Taras

    Hi! Thanks for the great article. Personally, I’ve used F33 on my laptop with btrfs about a month and I would say it pretty stable and reliable. But for the moment I switched back to the XFS, because it works much faster for me.

  8. ernesto

    On one of these articles I saw a discussion on some old school linux commands not working properly with btrfs (it could have been ‘df’ or ‘du’).

    Is this still the case?

  9. Sally

    Because I can’t take a risk with my current system, I am trying it as VM, but I have noticed that, when I divide partitions like ‘/’, ‘/home’ and give each one specific size, I see the size like to merge and they share the same size, is that normal, and if so, why is that? can’t I keep fixed size for each partition in Btrfs?

    • The way Btrfs allocates space is as it needs it, so free space for one btrfs volume (disk partition) with more than one subvolume (like / and /home for example) will show identical for all subvolumes since it is currently available for all subvolumes to use.

      • Sally

        In this case I can’t encrypt just one partition e.g. ‘/home’ which I think it’s not a good idea.

  10. Jared Gray

    Thanks for your excellent guide, Gergely (and of course the editors)! Because I had a lot of storage options, I decided to migrate my LVM/ext4 Fedora installation to an external mount point and then copy the data back to a new Btrfs filesystem. This approach considerably simplified moving off of LVM in particular. Even though my migration path was different than that described by this in-place tutorial, your guide was still instrumental in my own process.

    Just in case others decide to follow a similar approach to what I did, there is one caveat I wanted to mention expressly. If you have SELinux enabled on your Fedora system, which is currently the default, you will need to relabel the new filesystem to get your system booting again. You can do this simply by placing a file called ‘autorelabel’ on the Btrfs subvolume corresponding to your ‘/’ mount point. I can’t speak to whether this step is required when using the in-place migration tools discussed in the article, however.

  11. Jared Gray

    Correction: the file name is ‘.autorelabel’ not ‘autorelabel’. And warning: relabeling your entire file system is slow. With an NVME SSD and a two year-old installation of Fedora, I had to wait about five minutes for the process to complete. During this time, I was treated to a completely black screen. This is problematic because users may conclude that boot process has failed when in fact it is progressing.

    To be clear, the fix I suggested does indeed work (eventually), but it is a hammer- rather than a scalpel-type solution. If your file system contains a lot of files (more than one million) or you are using a conventional spinning hard drive, I advise against relabeling everything as a first line measure. Since I’m not an SELinux nerd myself, I will put a call out there to those who know of a more fine-grained solution than I do.

    In the meantime, my refined guidance is: before relabeling your filesystem, first verify that SELinux is the reason why your system will not boot. One way to do this is to disable SELinux policy enforcement temporarily and see if the system comes up afterwards.

    To disable SELinux policy enforcement for the next boot only, ensure your kernel command line contains ‘selinux=1’ and ‘enforcing=0’. You can do this in GRUB by hitting the ‘e’ key during boot and appending the above parameters to the line containing ‘vm-linuz’. If the system now boots, you can reasonably infer that SELinux file attributes were likely causing the problem.

    • … During this time, I was treated to a completely black screen. This is problematic because users may conclude that boot process has failed when in fact it is progressing. …

      I was never a fan of disabling the post screen that shows what is happening (and if anything is failing) during boot. You should be able to hit the Esc key to see the status messages.

  12. Tony Nalagan

    Wish I saw this article last November. My solution was less elegant and required considerable time to complete. I converted root, created an new home subvolume, and used gparted to shrink the original home partition while increasing the size of the new btrfs filesystem. Then migrating the data about 20 GB at a time, and repeating until all the data was transferred to the new home subvolume. Admittedly a brute force method.

  13. “The purpose of this article is to give you an overview about why, and how to migrate your current partitions to a Btrfs filesystem”

    Can’t find the why, only the how…

  14. b1tninja

    Further caution, you cannot rely on the snapshot as a backup

Comments are Closed

The opinions expressed on this website are those of each author, not of the author's employer or of Red Hat. Fedora Magazine aspires to publish all content under a Creative Commons license but may not be able to do so in all cases. You are responsible for ensuring that you have the necessary permission to reuse any work on this site. The Fedora logo is a trademark of Red Hat, Inc. Terms and Conditions