If you’re using CachyOS or any Arch-based distribution with Btrfs and want to enable hibernation, this guide will walk you through a clean and correct setup.

We’ll create a dedicated Btrfs subvolume for swap, configure the swap file correctly for compatibility, and set up everything needed for hibernation, including kernel parameters.

Why This Matters

Btrfs is great, but it introduces some complications when using swap files, especially for hibernation. The kernel needs to know the physical disk offset of the swap file, and that file must be non-compressed, non-COW, and stored in its own dedicated subvolume.

1. Clean Up Any Existing Broken Setup

sudo swapoff -a
sudo umount /swap 2>/dev/null || true
sudo btrfs subvolume delete /swap 2>/dev/null || true
sudo rm -rf /swap

2. Create a New Swap Subvolume

sudo mkdir -p /mnt/btrfs-root
sudo mount -o subvolid=5 /dev/disk/by-uuid/<YOUR_ROOT_UUID> /mnt/btrfs-root
sudo btrfs subvolume create /mnt/btrfs-root/swap
sudo umount /mnt/btrfs-root
sudo rmdir /mnt/btrfs-root

Replace <YOUR_ROOT_UUID> with the UUID of your Btrfs root. Find it using:

findmnt -no UUID /

3. Mount the Subvolume via /etc/fstab

Add this line to /etc/fstab:

UUID=<YOUR_ROOT_UUID> /swap btrfs subvol=swap,noatime,compress=no,space_cache=v2 0 0

Then:

sudo mkdir /swap
sudo mount -a

4. Create the Swap File

sudo chattr +C /swap
sudo fallocate -l 16G /swap/swapfile  # adjust size as needed
sudo chmod 600 /swap/swapfile
sudo mkswap /swap/swapfile
sudo swapon /swap/swapfile

Make sure it appears with:

swapon --show

5. Get the Resume Offset

sudo btrfs inspect-internal map-swapfile -r /swap/swapfile

You’ll get a number like 4546994. That is your resume_offset.

6. Update Kernel Parameters (GRUB)

Edit /etc/default/grub:

GRUB_CMDLINE_LINUX_DEFAULT="... resume=UUID=<YOUR_ROOT_UUID> resume_offset=4546994"

Then regenerate GRUB config:

sudo grub-mkconfig -o /boot/grub/grub.cfg

7. mkinitcpio Hooks

Edit /etc/mkinitcpio.conf and make sure resume is after udev:

HOOKS=(base udev autodetect microcode modconf kms keyboard keymap consolefont block filesystems resume fsck)

Then:

sudo mkinitcpio -P

8. Test Hibernation

sudo systemctl hibernate

After the system powers off, turn it on again. It should resume your session from swap.

Final Notes

• Don’t rely on /boot/efi/EFI/cachyos/grub.cfg; GRUB on EFI loads /boot/grub/grub.cfg.
• zram does not support hibernation; ensure your swapfile is active and recognized.
• Want to increase speed? Consider adding hibernate.compressor=lz4 to your kernel line.

Hibernation on Btrfs is not trivial, but once it’s done properly, it works just as well as with traditional setups. Good luck and happy hacking!