How To Install
Omarchy ships on btrfs and upstream is staying that way. You can still run ZFS. Nobody had written down how, so here are three routes, each one tested on Omarchy Quattro.
Which situation are you in?
1. Fresh machine
New install, whole disk available
Boot our ISO and get an encrypted root-on-ZFS Omarchy with ZFSBootMenu, boot environments, and a single passphrase prompt. Hands-off after a handful of questions.
Fresh root-on-ZFS install →2. Existing Omarchy → ZFS root
Already running Omarchy, want ZFS underneath it
There is no in-place btrfs to ZFS conversion. Here is the safe way to get there, and how to keep your old install bootable while you do it.
Convert to a ZFS root →3. Keep btrfs, add ZFS
Happy with your install, want ZFS for data
Leave the root filesystem alone. Put ZFS on /home, a scratch
pool, or a big spinning array. With snapshots, scrubs, and
zfs send to somewhere else.
Both give you snapshots. What differs is what you can do while the machine is broken.
Stock Omarchy already boots btrfs snapshots through limine and snapper, and for plenty of people that is enough. A ZFS root with ZFSBootMenu differs in ways that only show up on a bad day:
- The kernel and initramfs live inside the boot environment. Pick an older environment and you get the exact kernel and initramfs that worked with it. Roll back a root filesystem while the ESP still holds the newest kernel image and you can end up running an old userland under a new kernel.
- You get a shell with the pool already imported, before anything boots. From there you can list snapshots, roll one back, clone it, chroot into it, or read your logs. A bootloader picks an entry and boots it. It cannot do any of that.
- Boot environments are writable clones, not read-only snapshots. You can boot one, work in it, and keep it. Making it your permanent root is a property change rather than subvolume surgery.
- Nothing has to stay in sync. ZFSBootMenu finds the environments in the pool when it starts. No service generates menu entries that can drift from the snapshots you actually have.
If what you want is your files on ZFS, meaning snapshots, send and receive, checksums, and a pool you already replicate to a NAS, route 3 is less invasive and easier to undo.
What you need, whichever route you pick
| Requirement | Why | How to check |
|---|---|---|
| Omarchy Quattro (4.x) | Quattro is served entirely from Arch packages. omarchy-zfs
is a package that depends on it; the pre-Quattro
curl | bash layout is not supported. |
pacman -Q omarchy |
| x86_64 | The ISO and the published packages are x86_64. aarch64 Omarchy is not there yet upstream. | uname -m |
| UEFI firmware (routes 1–2) | ZFSBootMenu is an EFI executable. A BIOS/CSM-only machine cannot boot it. | [ -d /sys/firmware/efi ] && echo UEFI |
| Secure Boot off | The ZFS module is built by DKMS and ZFSBootMenu's EFI image is unsigned. Neither is signed by a key your firmware trusts. | mokutil --sb-state |
| A backup you have actually restored from | Every route below writes to disks. Route 2 destroys a working install by design. | - |
Why ZFS here at all
Omarchy is opinionated, and that is most of why it is good. btrfs is one of
those opinions. It is wired into upstream's boot story, with snapper and
limine-snapper-sync providing bootable snapshots. If that works for
you, use it. This project exists for people whose storage already runs on ZFS,
and who would rather not keep two mental models:
- Whole-pool native encryption. Not dm-crypt/LUKS
underneath a filesystem. Encryption is a property of the dataset, so
zfs sendcan move an encrypted dataset without ever decrypting it. - Replication that understands your data.
zfs send | receiveto a NAS, a second machine, or object storage, incrementally, with the snapshot as the unit. - End-to-end checksums and scrubs on every block, with self-healing when a pool has redundancy.
- One toolset if your TrueNAS box, your backup target, and your laptop all speak ZFS.
The tradeoff: ZFS is an out-of-tree module, so a kernel upgrade can outrun it. That is a real operational cost, and it is what this package spends the most effort defending you against. See the kernel-skew section.
Why a package and not a pull request
Omarchy does not support ZFS, and that is a product decision rather than an oversight. btrfs is wired into the installer and the snapshot boot flow, and a second filesystem would mean a second path to test on every release.
So this is not a fork, not a campaign, and not a request for anyone upstream
to carry our weight. omarchy-zfs is a package that
depends on stock Omarchy and re-homes the ZFS pieces as real,
package-owned files plus pacman hooks. You update Omarchy the normal way. Remove
our package and you are left with plain Omarchy.