Omarchy 4 day-one checklist: your first 48 hours

Checked against Omarchy 4.0.4, released 15 September 2026. Everything below was verified against the 4.0.4 source tree and against open issues on the tracker.

Hour one: three things that can lock you out

These are the items where a wrong choice costs you a reinstall. Do them before you customise anything.

1. Keep your disk passphrase to lowercase letters that sit in the same place on US QWERTY. Issue #8196 is an open report from a full-disk install on a French AZERTY laptop. The passphrase was enrolled under the French layout the installer had been told about, but the LUKS prompt at boot behaved as US QWERTY. AZERTY puts digits on the shifted row, so a passphrase containing digits could not be entered at all, and the reporter ended up reinstalling. Their advice: lowercase letters only, no digits or symbols, and on AZERTY avoid a, q, z, w and m, which swap positions against QWERTY. They expect QWERTZ and other remapped layouts to be exposed the same way.

On 4.x the packaged /etc/mkinitcpio.conf.d/omarchy_hooks.conf does bundle /etc/vconsole.conf into the initramfs so Plymouth applies your layout, but only when that layout types Latin letters. Cyrillic, Greek, Hebrew, Arabic, Thai and similar layouts are deliberately excluded, because bundling them would make a Latin passphrase untypeable. If you use one of those, the LUKS prompt is US QWERTY on purpose.

2. Check that your login password types on a US QWERTY greeter. This is a separate prompt with a separate bug. Issue #6880, filed against 4.0.0 on its release day, reports that the SDDM greeter always uses US QWERTY regardless of the system layout, because the greeter runs its own Hyprland instance whose config declares no input block. Issue #10842 confirms the same on 4.0.2 with Colemak and Russian, and adds that there is no layout indicator and no switcher on the greeter. Both are still open on 4.0.4.

Full detail on both prompts: non-US keyboard layout at LUKS and SDDM and layouts and locale.

3. Test snapshot rollback before you rely on it. The manual tells you snapshots are created on every update and restored from the Limine boot menu. Issue #8047 reports that on a stock install the restore path cannot run at all. The btrfs-overlayfs hook is in the shipped omarchy_hooks.conf, and it lays an overlay over / whenever you boot a read-only snapshot, which every Snapper snapshot is. limine-snapper-sync, the tool behind omarchy-snapshot restore, checks that / is btrfs before it does anything else, and under the overlay that check fails, so the restore exits with an error before it parses a single argument. Issue #9828 adds a second trap. A restore rolls back the root subvolume and leaves @home alone, which the manual confirms. Migration markers are written under ~/.local/state/omarchy/migrations/ in your home directory, so after a restore the work each migration did is gone from / while its marker still says done, and omarchy-migrate will not run it a second time.

Keep an ordinary backup of your home directory. See rollback with Snapper and Limine.

Day one: the setup pass

Run the update first. It brings in anything released since your ISO was built and applies the pending migrations that fix earlier bugs.

omarchy update

It requires sudo, creates a snapshot first, and logs to /tmp/omarchy-update.log. Confirm it actually printed something: issue #11630 reports omarchy update exiting silently with status 0 on 4.0.3, doing nothing and writing no log. There is an unattended form, omarchy update -y. See before you update checklist and what migrations do.

Then learn where configuration lives. Omarchy 4.0.0 moved user Hyprland configuration from .conf files to Lua. The 4.0.4 tree ships hyprland.lua, input.lua, monitors.lua, bindings.lua, looknfeel.lua and autostart.lua in ~/.config/hypr/, with xdph.conf and hyprsunset.conf still plain config. Issue #6933 shows the catch for upgraders: a bindings.conf left over from 3.x stays on disk but is no longer loaded, so custom hotkeys silently stop working. Guides written for 3.x that tell you to edit hyprland.conf no longer apply. See hyprland.conf to Lua migration.

Set your session keyboard layout in ~/.config/hypr/input.lua:

hl.config({
  input = {
    kb_layout = "us,dk",
    kb_options = "compose:caps,grp:alts_toggle",
  },
})

Set displays in ~/.config/hypr/monitors.lua. The shipped default is one catch-all rule, with the scale held in a local variable set to "auto":

local omarchy_monitor_scale = "auto"
hl.monitor({ output = "", mode = "preferred", position = "auto", scale = omarchy_monitor_scale })

List what you actually have with hyprctl monitors all before pinning anything. See multi-monitor.

The first 48 hours: what will actually block you

Screen sharing. Two open issues. #11221 reports that the share picker can draw one or more monitor cards outside the visible area of its Outputs tab, so a monitor is simply missing from the list, when your layout has no output positioned at x=0 or y=0. Upstream fixed this in August 2026, but the reporter found the hyprland-preview-share-picker-git package in Omarchy’s repository was built from a December 2025 commit, and notes that the non-git hyprland-preview-share-picker package, which is the one in the 4.0.4 base package list, is on a tagged release that also predates the fix. Omarchy selects that picker through custom_picker_binary in ~/.config/hypr/xdph.conf. The reporter’s workaround is to shift the whole layout so one output sits at 0,0. #10496 reports heavy rendering corruption in Google Meet when you start sharing while another participant is already sharing. Details and workarounds: screen sharing in Meet, Zoom and Teams.

Fractional scaling. Electron and Chromium apps are the weak point. #9904 reports the 1Password browser-unlock popup mapping at 402x371 logical pixels while its layout expects roughly 1.6 times that, clipping the password field at scale 1.6. #9907 reports Electron and Chromium secondary windows leaving stale or duplicated regions at the same scale, and believes it is not specific to 1Password, having seen similar corruption in Obsidian. Both are open. See fractional scaling and HiDPI apps.

Printers. Do not assume plug and play. #11814 reports an HP Smart Tank 529 over USB where the only option offered is a driverless queue that fails every job with universal filter failed. The reporter’s diagnosis is that hplip is not on the image, so there is no vendor PPD, and that the driverless path is broken for this class of inkjet; hplip is indeed absent from the 4.0.4 package lists. #11186 reports dropped and blank pages after updating to 4.0.3, traced by the reporter to libcupsfilters jumping to 2.2.1-2 while cups-filters stayed at 2.0.1-2. See printers and scanners.

Wi-Fi and Bluetooth around suspend. #11377 reports a Broadcom brcmfmac adapter wedging NetworkManager and wpa_supplicant into unkillable D-state, which aborts suspend and leaves the machine awake with dead Wi-Fi. #11264 reports a T2 MacBook Air where Bluetooth never powers on at boot and every suspend fails on a D3 timeout. Both are open. Two commands are worth knowing before you need them:

omarchy restart wifi
omarchy restart bluetooth

Both are small scripts. omarchy-restart-wifi runs rfkill unblock wifi, switches the NetworkManager radio back on and rescans; omarchy-restart-bluetooth only runs rfkill unblock bluetooth. Neither restarts a service or reloads a kernel driver, so they help with a soft-blocked radio, not with the driver wedge in #11377. See suspend and sleep, Wi-Fi and Bluetooth.

What to watch for on newer versions

All fifteen issues cited here were still open on 2026-09-16, the day after 4.0.4 shipped. They were filed against 4.0.0 through 4.0.3, and none has a fix attributed to any release, so check each thread before assuming a point release cleared it. Nothing here has been checked against any release after 4.0.4.

If you are coming from 3.x rather than a fresh install, the config format change is the bigger shock than any single bug. Start with what replaces what and tiling window manager survival.

Official references: the system snapshots chapter, the keyboard, mouse and trackpad chapter, and the updates chapter.