Swap space is a standard component of most operating systems. It’s effectively reserved disk space for accommodating a system when it needs more RAM than it has available. I recommend the opensource.com article An Introduction to Swap Space on Linux Systems as a great primer on the topic.

There are two approaches to providing swap space on Linux, swap partitions and swapfiles. Since version 5.0 of the Linux kernel, Btrfs swap files are supported according to the section Does Btrfs support swap files? in the Btrfs Wiki FAQ. Switching to Btrfs as my default filesystem, I recently set this up have created this tutorial get yourself a swapfile set up on Btrfs.

Tutorial

This tutorial contains the necessary steps to create a Btrfs swapfile. The reference system is running elementary OS 5.1 and a flat Btrfs layout. As a matter of preference, the commands here use the fish shell's syntax.

I have not been able to get hibernation working when using a Btrfs swapfile. You should consider a dedicated, encrypted swap partition if you desire this feature.

  1. Mount the root Btrfs filesystem to create a subvolume.

    sudo mount (df --output=source / | tail -n 1) /mnt
  2. Create a dedicated Btrfs subvolume for swap in order to exclude the swapfile from snapshots.

    sudo btrfs subvolume create /mnt/swap
    Create subvolume '/mnt/swap'
  3. Set the appropriate permissions on the swap subvolume so that only the owner, the root user in this case, has access to the subvolume.

    sudo chmod 700 /mnt/swap
  4. Create a directory at where the swap subvolume will be mounted.

    sudo mkdir /swap
  5. Add the subvolume to /etc/fstab.

    echo (df --output=source / \
      | tail -n 1)" /swap btrfs defaults,noatime,subvol=swap 0 0" \
      | sudo tee -a /etc/fstab
    /dev/mapper/sda2_crypt /swap btrfs defaults,noatime,subvol=swap 0 0
  6. Now mount the swap subvolume according to the rules just add in fstab.

    sudo mount /swap
  7. Create an empty swapfile within the swap subvolume.

    sudo truncate -s 0 /swap/swapfile
  8. Disable Copy-on-Write for the swapfile.

    sudo chattr +C /swap/swapfile
  9. Make sure to disable compression on the swapfile.

    sudo btrfs property set /swap/swapfile compression none
  10. Allocate the file with as much space as there is RAM on the system.[1]

    sudo fallocate -l (free -h | awk 'NR == 2 {print $2}') /swap/swapfile
  11. Only allow access to the swapfile by its owner, the root user, to prevent snooping.

    sudo chmod 600 /swap/swapfile
  12. Initialize the swapfile.

    sudo mkswap /swap/swapfile
    Setting up swapspace version 1, size = 7.8 GiB (8355049472 bytes)
    no label, UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  13. Enable the swapfile!

    sudo swapon /swap/swapfile
  14. Add the swapfile to /etc/fstab so that systemd will initialize it automatically when booting the system.[2]

    echo "/swap/swapfile none swap defaults 0 0" | sudo tee -a /etc/fstab
  15. Verify there are no errors in /etc/fstab.

    sudo findmnt --verify --verbose
  16. Set a lower swappiness in an attempt to improve performance.

    This is described in the ArchWiki’s page on Swap in the Swappiness section. A lower setting as used here advises the kernel to avoid swapping.

    echo vm.swappiness=10 | sudo tee /etc/sysctl.d/99-swappiness.conf
    vm.swappiness=10

    This setting will be applied at the next reboot.

References

Conclusion

You should now know all you need to know to make a Btrfs swapfile on Linux.


1. For better recommendations on the size of your swapfile, refer to the table Recommended System Swap Space in the Recommended Partitioning Scheme section of Fedora’s installation documentation.
2. How systemd handles swap is documented thoroughly in the corresponding man page: systemd.swap(5).