OPINIONATED OMARCHY
TROUBLESHOOTING CORPUS
790
RECORDS
790
AUDITED
0
UNCHECKED
2388
SOURCES
LIVE
hyprland-config low occasional DISPUTE

Make omarchy_default_bindings = false actually disable Omarchy's keybindings

omarchyhyprland
AUDITED Audited against its sources and confirmed accurate. · checked against Omarchy omarchy 4.0.4-1 on 2026-10-05
AUDIT NOTE

Every claim checked against the 4.0.4-1 files on this machine and the 0.56.2 source. /usr/share/omarchy/default/hypr/omarchy.lua wraps media, clipboard, tiling, utilities, voxtype and applications in if _G.omarchy_default_bindings ~= false, and autostart, envs, looknfeel, input and windows load unconditionally. default/hypr/helpers.lua o.preinstalled_bindings_enabled() reads _G.omarchy_preinstalled_bindings first and otherwise returns false when ~/.local/state/omarchy/preinstalls-removed exists, and applications.lua calls it at load time. The shipped config/hypr/hyprland.lua carries the flag commented out above require("default.hypr.omarchy"), and hypr.bindings is required after it, so a flag set there or below the require has no effect, and a local declaration is not the _G field. The fix's replacement binds match the defaults exactly (applications.lua:2, utilities.lua:1 and :8, tiling.lua:1), and o is a global from helpers.lua, which loads even with the flag off. The emergency-bind claim in danger is confirmed in ConfigManager.cpp postConfigReload: emergency mode trips only when m_errors is non-empty AND no keybinds exist, with SUPER+Q, SUPER+R, SUPER+M. hyprctl -j binds | grep -c '"key"' printed 228 here, matching the verify. omarchy-menu-keybindings --print exists (line 583). Not exercised live: the flag was not set on this workstation.

RISK

With omarchy_default_bindings = false and nothing in bindings.lua, the session has no keybindings at all. Hyprland's emergency binds (SUPER+Q terminal, SUPER+R run, SUPER+M exit) only appear when a config error left zero binds, so a clean config with no binds gives you no way to open a terminal. Write the replacement binds first. Recovery is a TTY (CTRL+ALT+F3), editing the file there, and saving.

Symptom

I set omarchy_default_bindings = false (or omarchy_preinstalled_bindings = false) to start from a clean keymap, reloaded, and every Omarchy binding still works: SUPER+SPACE still opens the menu, SUPER+RETURN still opens the terminal, and my own binds on the same keys fire as well as Omarchy's.

Cause

Omarchy 4 reads these flags once, as globals, at the moment its defaults load. /usr/share/omarchy/default/hypr/omarchy.lua wraps the binding modules in if _G.omarchy_default_bindings ~= false then ... end, and o.preinstalled_bindings_enabled() in default/hypr/helpers.lua checks _G.omarchy_preinstalled_bindings while default/hypr/bindings/applications.lua loads. ~/.config/hypr/hyprland.lua runs require("default.hypr.omarchy") partway down. The flag is ignored if it is:

  • set below that require line, because the binds are already registered,
  • set in ~/.config/hypr/bindings.lua, which is required after the defaults,
  • declared local omarchy_default_bindings = false, which is not the global _G field the check reads,
  • left commented out. The shipped hyprland.lua carries it as -- omarchy_default_bindings = false.

The flag only skips binding modules (media, clipboard, tiling, utilities, voxtype, applications). Environment, look, input and window rules still load.

Fix

Edit ~/.config/hypr/hyprland.lua so the global is set **above** the defaults:


dofile((os.getenv("OMARCHY_PATH") or "/usr/share/omarchy") .. "/default/hypr/bootstrap.lua")

omarchy_default_bindings = false          -- global, no `local`, uncommented
-- or keep window-manager binds and drop only the app/web-app ones:
-- omarchy_preinstalled_bindings = false

require("default.hypr.omarchy")

Then add every bind you want in ~/.config/hypr/bindings.lua, at minimum a terminal, a launcher and a way to log out, before you save hyprland.lua:


-- ~/.config/hypr/bindings.lua
o.bind("SUPER + RETURN", "Terminal", { omarchy = "terminal" })
o.bind("SUPER + SPACE", "Omarchy menu", "omarchy-menu toggle")
o.bind("SUPER + ESCAPE", "System menu", "omarchy-menu toggle system")
o.bind("SUPER + W", "Close window", hl.dsp.window.close())

For omarchy_preinstalled_bindings there is also a file switch that needs no Lua: the helper treats the existence of ~/.local/state/omarchy/preinstalls-removed as false unless the global is set.

To replace only a few defaults, leave the flag alone and use hl.unbind("SUPER + SPACE") followed by your own bind in bindings.lua, as the shipped file's comments show.

Verify

hyprctl -j binds | grep -c '"key"' drops from about 228 (the 4.0.4 default count on this machine) to the number you defined, and omarchy menu keybindings --print lists only your binds. Read from the 4.0.4 source on this machine. Not exercised live, to avoid stripping the workstation's binds.

Sources

omarchy-default-bindings-false-no-effect