Boot On BTRFS With Debian

This tutorial will explain you how to boot from a BTRFS filesystem with kernel 2.6.31-RC4 and BTRFS 0.19. BTRFS is a new filesystem with some really interesting features like online defragmenting and snapshots. BTRFS is an experimental filesystem, use at your own risk. The kernel used is also experimental.

This tutorial worked fine for me but I don't guarantee that this will work for you, and decline all responsibility for any problem you might have.


Pre-requisites :

Debian install media
ubuntu liveCD
Internet connection (ethernet)


Step 1: installing Debian

Boot onto Debian CDrom, choose install and answer to the questions until you have to partition the hard drive.

Then you choose manual. We have to make at least 2 partitions (I advise to do three) in order to be able to boot (I think that GRUB doesn't support BTRFS boot yet so it will have its own partition).

The first one will contain the linux kernel and grub, the bootloader, I will explain these terms later in the tutorial. I think that 250MB will perform well for this partition.

Type : EXT2
Mount point : "/boot"
Bootable flag : yes.
Then select "done with this partition".

For the other one, you can select to automatically create partitions or make it yourself with mountpoint "/" and type "ext3"
(you can take all the space if you don't want swap otherwise reserve a space for swap with your ram quantity in GB + 500MB to be able to hibernate).

You can add a swap file if you want to (if you don't want you'll have some warnings), type is "swap area".

Then write the settings to drive and answer the questions (I personnally install nothing except the base system, so I got no "*" at all in the software selection but feel free to install what you want) and say yes when it asks you to get GRUB onto the MBR (master boot record). Debian is now installed.


Step 2 configuring aptitude:

Aptitude is a package manager, it means that it can grab and install software for you with just the software name.

Log in as root (with the password you set during installation).

I'm used to use vim editor to modify my configuration files but you can use another one if you want to.

Let's install vim:

aptitude install vim

We now configure aptitude to grab more up to date software:

vim /etc/apt/sources.list

Copy a line which looks like that by pressing 2 times "y":

deb lenny main

The web address will probably change but that's normal.

Press "p" two times and then "i" and change lenny into sid on a line and into testing on the other.

You should see three lines one ending by "sid main", another by "testing main" and the last by "lenny main".

Press "escape" button then type :wq to save and quit.


aptitude update

If you want to upgrade your system to unstable version of debian type:

aptitude dist-upgrade

Otherwise just skip and type directly:

aptitude install zlib1g-dev zlibc kernel-package btrfs-tools libncurses-dev bzip2

Debian has 3 major branches, the unstable which has performed only few tests but is up to date, testing that performed most of the tests and stable that performed all the tests.

If you want to be in unstable (sid), go to step 3, otherwise comment out the line containing "sid" an you'll be in testing. If you want to be in stable comment out testing and sid lines.


Step 3: compiling the kernel

The Linux kernel is the system's heart, without it, you wouldn't be able to do anything.

We will have to modify some of the options, but don't worry, you'll be able to boot back on the old kernel if you're in trouble.

That's the purpose of the bootloader, GRUB which permits you to select which kernel you want to boot and even if you want boot into Microsoft Windows.

Let's change directory:

cd /usr/src

We must download the kernel, we also need a patch because BTRFS 0.19 only works with an experimental kernel.


Then we must extract them, move the patch to the right place and patch the kernel:

tar xvjf linux-2.6.30.tar.bz2
mv linux-2.6.30 linux
bzip2 -d patch-2.6.31-rc4.bz2
mv patch-2.6.31-rc4 linux
patch < patch-2.6.31-rc4 -p1

We will now generate a "graphical" interface for the kernel configuration, go to FileSystems and get a " * " in front of BTRFS and BTRFS posix categories.

You can tweak the kernel a little more if you know what you do but I won't speak about it here, let's focus on the subject:

make menuconfig

Then save the config to .config (default name) and exit.

We are now ready to launch the compilation, this means we will build something we can install on the machine and also that you can get a coffee because this is going to take a while (20 minutes for recent computers):

make-kpkg --initrd kernel_image kernel_headers

Then we install the new kernel:

cd ..
dpkg -i *.deb

We clean the directory, do not delete the headers:

rm -rf linux
rm -rf *.bz2

We now generate a file which will help the kernel to load all the things it needs during the boot which is called initrd and we update the bootloader:

mkinitramfs 2.6.31-rc4 -o /boot/initrd.img-2.6.31-rc4

You can now try to reboot, we are done for kernel compilation and installation.

If you have trouble go back to step 3.

Step 4: preparing the BTRFS boot:

We must now prepare the system for the BTRFS first boot. Indeed our system is now able to read BTRFS but the system is not configured to boot on it. We are still able to modify the files now but after the conversion of the FileSystem, we won't be able to modify anything, so we have to do it right now.

There are two ways of identifying a filesystem: a UUID (which is a unique alpha-numerical identifier) and an identifier that looks like /dev/sda3. The advantage of the UUID is that it rarely changes even on USB devices but we will convert the FileSystem and the UUID may change, so we can't trust it. However the /dev identifier won't change with our configuration, so we can use it.

By default the system uses UUID so we'll change that.

Identify our partition "/"

fdisk -l

Find out which partition number is your "/", this is the partition with biggest size if you made the partition like I said above.

On my computer this was /dev/sda3 but it can be something else (probably /dev/sda2) so change the "%" by the right number.

It's possible that you haven't /dev/sda but something like /dev/hda or /dev/sdb in this case use what's printed on the screen instead of /dev/sda.

vim /boot/grub/menu.lst

Type /initrd

Then edit (with "i") and change root=uuid=complicated_thing by root=/dev/sda% for the line which as 2.6.31-rc4 in it.

Exit and save.

The fstab is a file that gives the options you pass to the filesystem to boot, for exemple, you can activate compression under BTRFS or avoid writing on a filesystem. We must replace the UUID of the "/" in it by /dev/sda%:

vim /etc/fstab

Seek something like UUID=complicated_thing / ext3 errors=remount-ro 0 1 and replace by /dev/sda3 / btrfs errors=remount-ro 0 1 exit and save


Converting the Filesystem

There is a utility in BTRFS that converts EXT3 to BTRFS filesystem, but you can't use it while your system is running, this is called an offline converter.

So we'll have to find another way to do it, that's where we use the ubuntu live CD. reboot your system and boot on the Ubuntu LiveCD.

Once the CD finished his boot, use keyboard shotcurt "alt+F2", type "gnome-terminal" (or "konsole" if you picked up kubuntu), then log with the root account with:

sudo su

Perform step2 including "aptitude update".

We don't want to install all the stuff we installed on the debian to build the kernel so just type:

aptitude install btrfs-tools
btrfs-convert /dev/sda%

If everything went well, you are now booting Debian properly on a BTRFS file system.

I hope you enoy this tutorial and that it was helpful.

Do not hesitate to comment on this tutorial, to help me improve it, and, please, forgive me for my bad English (I'm French).

Share this page:

Suggested articles

11 Comment(s)

Add comment


By: Anonymous

If you're going to do it debian, do it right.

By: Jason

If you install Grub2, you might be able to boot directly from a BTRFS partition. If you don't have a spare machine on which losing the entire contents of the hard drive is acceptable, virtualization can come to the rescue.

By: Henk Koster

Pretty good tutorial! I have a few points, though:

1. It is not necessary to patch the 2.6.30 kernel, as patched 2.6.31 kernels can be downloaded from the same URL as the patches; the latest is now the linux-2.6.31-rc5.tar.bz2 archive.

2. When running "make menuconfig" the BTRFS module is already marked (M); it is important that this be changed to (*) (as is the case with the EXT2 file system).

3. When booted with the Ubuntu 9.04 liveCD, just download the btrfs-tools package from for unstable/Sid (either i386 or amd64 will work on the Ubuntu generic kernel), then install it with "dpkg -i btrfs*.deb". No need to "repeat step 2"...


By: Anonymous Cowboy

It's actually not necessary to mark the BTRFS and the EXT2 file systems with (*) to have them built-in to the kernel. If you use an initrd, it will load the needed file system modules before trying to mount the root file system. If the initrd is properly set up, that is (and it should be, as if by magic).


Hi everyone, thanks for the replies.

 I was very busy for the last few days so I couldn't answer before.

 Yes you can use any liveCD debian-based that you want, I used Ubuntu because it was on my desk already burned and I didn't want to download another liveCD.

 For grub, I installed debian from netinstall CD and I had grub installed with it but I'll probably test with grub2 if I have some time. And if this works I'll update the tutorial to get the two methods in it.

 Yes, you are right we can download the rc kernel without patching, but I didn't see the "F" link on so I supposed that there were only the patch and the patch baseline but you can download the kernel here and skip the patch step.

 I don't think that marking BTRFS with * instead of using it as a module is that important. I'm just used to compile all the thing I always need without using a module. But since I make an initrd, I think this will boot properly but I haven't tested it.

Indeed you can use the web to download the package without using apt, I've repeated step2 to be sure there was no dependency problem. But in the actual version I don't think there is problems.


I'll try to find some time to test with grub2 and to see if BTRFS as module is enough to boot and if there is something to edit I'll do it.

Thanks for the comments.


By: Damijan Bec

I think that you skipped the most important partition


It saved my a*** so many times that don't even count Not to mention you can install another distribution without losing your desktop and other personal settings. Have switched from Fedora to Opensuse and end up with Debian without losing a single KDE and other application settings.

Never forget to create /home!


By: Dirk Heinrichs


you don't need any additional partitions anymore, that's what btrfs is all about. Just create a subvolume and mount it whereever you want (mount -osubvol=thesubvolume ...). And then, I wouldn't create one for /home, but one for each users /home/<user>.



By: mario

I did the very same with Ubuntu Karmic (alpha3) just yesterday. Karmic already comes with a 2.6.31rc kernel and the btrfs module available.

While the installer doesn't yet let you choose btrfs for the root filesystem, it can be made working with a few steps. I tried the btrfs-convert method, too, but that leaves the old ext3 filesystem meta data in place (wasted filesystem space for me) - snapshots cannot be deleted yet with btrfs 0.19.

Basically I did: use the alternate/netboot installer of Karmic, and created a standard installation with ext3 root / and ext2 boot/ filesystem first. Then I booted that up, and added the modules "btrfs" and "libcrc32c" and "zlib_deflate" and "crc32c" (VERY IMPORTANT!) to /etc/initramfs-tools/modules, then run a update-initramfs. /etc/fstab should be adapted then as well. I also copied those modules and mkfs.btrfs to /boot. After again booting to a livecd or alternate installer / rescue mode, you can then load the kernel modules (btrfs and crc32c) from boot/. And now the simplistic workaround to btrfs-convert: I just made a tar backup of my ext3 root filesystem to an external hdd (flash stick would have sufficed). Then I deleted the rootfs - with mkfs.btrfs - creating a clean root system. Mount the new btrfs root with -o compress,ssd options. Then I simply extracted the backup back onto the new btrfs root system. And voila, reboot, it works. (I had some error messages from cryptoroot, see /usr/share/initramfs/.../local-top/..., but it boots anyhow.)

Since I use a small 4GB ssd (compactflash), I wanted to try how much btrfs compression saves. The whole Karmic base system and ubuntu-desktop occupy just 1.0GB, instead of >3 GB I saw earlier. Seriously, this should become the new default for netbook distributions.

By: Harri

... you don't boot from btrfs. You boot from ext2. AFAICS grub still lacks support for btrfs.

By: Klaus

Please take your article offline - it didn't make much sense at the time it was posted, but now it's completely outdated and less than worthless.

By: Jeremy


BTRFS and linux have changed so much since this was written, than even trying to follow any of its ideas is downright dangerous.  Please take this page offline.