Roll back a bad Omarchy update with snapper and Limine

Checked against Omarchy 4.0.4 (2026-09-15) and the v4.0.4 source tree.

Omarchy snapshots the root Btrfs subvolume with snapper before every update, and limine-snapper-sync publishes those snapshots as entries in the Limine boot menu. That is your rollback. It covers the system, not your files.

The fix

1. Reboot. If the machine goes straight to the LUKS passphrase prompt, you have direct boot enabled, so interrupt the firmware and pick Limine from your BIOS boot menu first.
2. In Limine, open the Snapshots submenu and pick the entry from before the update. Each entry carries a date, and the Omarchy version recorded at snapshot time shows in the bottom left corner. That version string is the snapshot description, because omarchy-snapshot labels each snapshot with the output of omarchy-version.
3. Boot it and log in. The manual describes a notification that offers to restore for you. Do not wait for it on 4.x: Omarchy 4 ships an autostart override that hides limine-snapper-notify, and a migration disables any copy an upgraded machine already had.
4. Run the restore from a terminal:

sudo omarchy-snapshot restore

That is a thin wrapper. Under the hood it runs sudo limine-snapper-restore, which is deliberately hidden from the app launcher.

5. Reboot into the restored system.

If you only want a snapshot before doing something risky, that is the same tool:

omarchy snapshot create

Verify it worked

After the reboot, confirm you are on real Btrfs and not still inside a snapshot boot, and confirm the version:

findmnt -no FSTYPE,SOURCE /
omarchy-version
sudo snapper -c root list

findmnt should report btrfs, and the source should not contain a /snapshot path component. omarchy-version reads the installed omarchy package version from pacman, so on a restored root it should report the older release you rolled back to. snapper -c root list shows the snapshots that survived, with the version string in the description column.

Why it happens

The pieces are ordinary Arch parts wired together by Omarchy.

omarchy-update calls omarchy-snapshot create as one of its first steps, before any package is touched, and right after the package cache prune. The comment in the script explains the ordering: the cache lives on the subvolume about to be snapshotted, so pruning afterwards would free nothing until the snapshot ages out.

omarchy-snapshot create lists every registered snapper config and, for each one, runs snapper -c <config> create -c number -d <version> followed by snapper -c <config> cleanup number. A missing snapper is the one silent skip: the script exits 127 and the update ignores that specific code. Any other failure prints a warning and the update continues anyway, so an update never blocks on a failed snapshot.

Retention comes from the template at default/snapper/root, installed to /etc/snapper/configs/root. It sets NUMBER_CLEANUP="yes", NUMBER_MIN_AGE="0", NUMBER_LIMIT="5", NUMBER_LIMIT_IMPORTANT="5" and TIMELINE_CREATE="no". So you get the last five update snapshots and no hourly ones. The install step also writes /etc/conf.d/snapper with SNAPPER_CONFIGS="root", disables snapper-timeline.timer, and enables snapper-cleanup.timer and limine-snapper-sync.service.

The boot entries come from the Limine drop-in at /etc/limine-entry-tool.d/omarchy-defaults.conf, which sets MAX_SNAPSHOT_ENTRIES=6 and puts Snapshots last in the boot order. Six, not five, because limine-snapper-sync can see a newly created sixth snapshot before cleanup brings the count back down.

One 4.x change worth knowing: a migration shipped in 4.0.0 deletes leftover timeline snapshots from earlier defaults. Older installs ran hourly timeline snapshots, later configs stopped creating them but never removed the old ones, and number cleanup skips anything marked Cleanup=timeline, so they accumulated. The migration only runs when your config still has TIMELINE_CREATE="no", and it deletes in batches of twenty so a DBus timeout does not take the whole migration run down.

What a rollback does not give you back

• Your home directory. On the standard Omarchy layout, /home is a separate Btrfs subvolume (@home, alongside @ and @log), so it is not part of the root snapshot. Good for reverting a broken update, useless for recovering deleted files. Issue #5361 reports the opposite experience on 3.5.1: a restore brought back ~/.config and screenshots from the home directory, and nobody explained it in the thread. A /home that lives inside the root subvolume instead of @home would behave that way, so check findmnt -no SOURCE /home before you count on the separation.
• ~/.config. This is the sharp edge. Roll back to a release whose libraries or apps wrote configs in an older format, and you keep the new config files. Issue #5916 is a clean example: a user rolled back from 3.8.0, the release that moved the Hyprland configs from .conf to .lua, and was left with Lua configs the older version could not use. Running omarchy reinstall configs did not help either, because it pulled the 3.8.0 configs straight back.
• /boot. That is the EFI system partition, a separate FAT filesystem outside Btrfs entirely. Kernels and the unified kernel image there are not snapshot content.
• Nested subvolumes. Btrfs snapshots do not recurse into nested subvolumes, so anything you or the installer split out is outside the picture.

If that did not work

Restore fails with “You are not in Btrfs”. Issue #8047 reports that btrfs-overlayfs, which Omarchy has in its mkinitcpio HOOKS line since 4.0.0 and still has on the development branch, mounts an overlay over / in every read only snapshot boot, and that limine-snapper-sync then refuses to run because / is no longer Btrfs. The report is detailed and unanswered by maintainers, so treat it as reported rather than confirmed, and check on your own machine from inside a snapshot boot:

findmnt -no FSTYPE /
sudo btrfs property get / ro

If the first prints overlay, the restore path will not run there. The reporter’s workaround, which they say they verified end to end and which nobody else has confirmed, is a drop-in that filters the hook out. It has to sort after omarchy_hooks.conf, because that file assigns HOOKS outright rather than extending it, hence the zz- prefix. Create /etc/mkinitcpio.conf.d/zz-no-btrfs-overlayfs.conf:

_hooks=()
for _h in "${HOOKS[@]}"; do
  [[ $_h == "btrfs-overlayfs" ]] || _hooks+=("$_h")
done
HOOKS=("${_hooks[@]}")
unset _hooks _h

Then rebuild with sudo limine-mkinitcpio, not mkinitcpio -P, and take a fresh snapshot. Existing boot entries stay pinned to the initramfs that was current when they were taken, so an old entry keeps loading the overlay and looks like the fix failed. Dropping the hook also gives up the writable snapshot boot it provides, and you are editing a boot-critical file, so have a live USB within reach.

“No Snapper configs found, so no snapshot was created.” Issue #10421 points out that a failed sudo, for example with no controlling terminal or a mistyped password, produces the same empty output as having no configs, so the script blames the wrong thing. Check first with sudo snapper list-configs. If a config exists, do not run the suggested install/config/snapper.sh, because it overwrites /etc/snapper/configs/root with the template.

“IO Error (.snapshots is not a btrfs subvolume)”. Snapper needs /.snapshots to be a subvolume, and a snapshot of @ carries it only as a plain directory, which is why Omarchy’s own factory reset script repairs it afterwards. Issue #11100 ties the error to machines restored from an rsync, tar or clone backup, which flattens /.snapshots the same way. Issue #9097 hit the similar subvolume is not a btrfs subvolume on a fresh 4.0.1 install and only cleared it by reinstalling from USB. Verify with sudo btrfs subvolume show /.snapshots before doing anything destructive.

The snapshot step fails during an update. If you run a swapfile on the root subvolume, the kernel refuses to snapshot it. Issue #6456 reports this from a pre-4.0.0 development build, where the update still aborted at that step; on 4.0.x it continues without the snapshot. The workaround is swapoff before the update and swapon after.

No snapshots appear in Limine at all. Check the two services that feed it, then refresh the boot config:

systemctl status limine-snapper-sync.service snapper-cleanup.timer
sudo limine-snapper-sync

Issue #6629 reports limine-snapper-sync sitting inactive because of a missing dependency and a missing snapper root config. If your /home is a separate subvolume and you expected it covered, note issue #9619: the Omarchy install step rewrites SNAPPER_CONFIGS to root alone, which de-registers a home config you added yourself.

Everything is still broken after a rollback. omarchy reinstall resets Omarchy’s default packages and configuration files, puts you back on the stable channel and downgrades packages that are too new. It also overwrites your changes to the Omarchy defaults, so keep it as the last step.

Related

• Before you update checklist
• Upgrading 3.x to 4.0 Quattro
• What migrations do
• Official manual: System snapshots and Updates