Keyboard layout, caps:escape and touchpad settings are ignored under Hyprland
Checked on this workstation (omarchy 4.0.2-1, omarchy-settings 4.0.2-1, hyprland 0.56.2-1, kernel 7.1.9-arch1-2) and against the three Hyprland wiki pages the record cites, all of which still resolve and still say what the record claims. Confirmed here: the record contains no hyprlang anywhere, every input option name, type and range in its block matches the Variables page, hl.device({ name = ... }) is the current per-device form (Omarchy's own default/hypr/disabled-input-device.lua and omarchy-toggle-input-device use it), hyprctl switchxkblayout <device|current|all> next|prev|ID matches hyprctl switchxkblayout --help on 0.56.2, hyprctl eval exists on 0.56.2, hyprctl getoption input.kb_layout and input:kb_layout both work, and both wiki traps hold verbatim. The Omarchy claim is confirmed by reading /usr/share/omarchy/default/hypr/input.lua locally and at omacom/omarchy@quattro: it parses /etc/vconsole.conf, and ~/.config/hypr/input.lua here is byte-identical to the packaged fully commented-out template and is required after default.hypr.omarchy, so a user override genuinely wins. Five things were wrong or missing. First, kb_options replaces rather than merges, so the record's example silently drops Omarchy 4's compose:caps,shift:both_capslock_cancel, and its caps:escape collides with compose:caps because both claim Caps Lock (both option names verified in /usr/share/X11/xkb/rules/evdev.lst). Second, sudo localectl set-x11-keymap fr with no further arguments wipes XKBMODEL and XKBOPTIONS, confirmed in systemd's localectl.c where the omitted positionals are sent as empty strings, and this machine's /etc/vconsole.conf carries XKBMODEL=pc105+inet and XKBOPTIONS=terminate:ctrl_alt_bksp to lose. Third, switchxkblayout current targets the main: yes keyboard, which on this machine is hl-virtual-keyboard-fcitx5 and not anything the operator types on, a trap Omarchy's own bar widget source documents. Fourth, the record told the reader to get a device name from hyprctl devices but gave two invented names and no rule for the lowercase-hyphen form, so the corrected fix prints them with hyprctl -j devices and uses real ones. Fifth, Omarchy 4 ships a supported surface the record ignores: the omarchy.keyboard-layout bar widget added by migration 1786279107, present in ~/.config/omarchy/shell.json here, which appears once kb_layout has more than one entry and cycles on click. The corrected fix also answers whether an update eats the edit: migration 1781485962.sh sha-gates the copy, so only a still-stock input.lua is replaced. There is no omarchy-* command for setting the layout. ls /usr/share/omarchy/bin | grep -iE 'keyboard|input|layout|xkb' returns only RGB-lighting theming, the menu text-input helper and the touchpad enable toggle, so hand-editing input.lua is the supported path and not a workaround. The touchpad half stays: the symptom names it and the root cause is the same, that Hyprland programs libinput itself, but the corrected block now labels which of those lines Omarchy 4 or Hyprland already sets by default so the reader is not told to change settings that are already in force. Cause, symptom, danger, severity and frequency all held and are unchanged. NOT exercised: nothing was written, no reload, eval, keyword or dispatch was run, and no layout was switched, because this is the operator's live graphical session. The per-device kb_layout override and resolve_binds_by_sym were verified from the wiki and from the option table only, not by applying them here.
Setting a single non-Latin kb_layout (ru, gr, th, ua, ...) with no Latin layout first means keybinds that use Latin keysyms stop firing, including your terminal and launcher binds, leaving a desktop you cannot drive. Always lead with a Latin layout (kb_layout = "us,ru") and add a switch option such as grp:alts_toggle, which is exactly what Omarchy does for you at install time.
Symptom
setxkbmap fr has no effect, localectl status shows the right layout but Hyprland still types QWERTY, /etc/X11/xorg.conf.d/00-keyboard.conf is ignored, and caps:escape / compose:caps never engage. On a laptop: two-finger right-click, natural scrolling and disable-while-typing behave nothing like they did before. On Omarchy, editing ~/.config/hypr/input.lua appears to do nothing because everything in it is still commented out.
Cause
Hyprland is a Wayland compositor: it programs the keymap through libxkbcommon itself and never reads /etc/X11/xorg.conf.d/00-keyboard.conf, and setxkbmap only touches an already-running X server, which Hyprland is not. Input settings live in the compositor's own input section, plus optional per-device blocks. Two further traps: keybinds resolve against the **first** entry in a comma-separated kb_layout unless you set resolve_binds_by_sym, and a per-device layout does not change the keybind keymap at all. On Omarchy 4, /usr/share/omarchy/default/hypr/input.lua derives kb_layout/kb_variant from XKBLAYOUT/XKBVARIANT in /etc/vconsole.conf and prepends us, for layouts that cannot type Latin letters, so the layout you want may be set system-wide and still not be first.
Fix
**First, see what is actually in effect.** Both separators work on 0.56:
hyprctl getoption input:kb_layout
hyprctl getoption input:kb_options
hyprctl devices
**Set it in the compositor.** Plain Hyprland: ~/.config/hypr/hyprland.lua. Omarchy 4: ~/.config/hypr/input.lua, which ships as one fully commented-out hl.config block, so nothing in it takes effect until you uncomment it. ~/.config/hypr/hyprland.lua calls require("default.hypr.omarchy") and only then require("hypr.input"), so your file is read after Omarchy's defaults and wins.
hl.config({
input = {
kb_layout = "us,fr",
kb_variant = ",", -- one comma-separated entry per layout, or one for all
kb_model = "",
-- kb_options REPLACES the previous string, it does not merge. Omarchy 4 sets
-- "compose:caps,shift:both_capslock_cancel" in
-- /usr/share/omarchy/default/hypr/input.lua, and this line drops both unless you
-- repeat them. caps:escape and compose:caps both claim Caps Lock, so pick one.
kb_options = "compose:caps,shift:both_capslock_cancel,grp:alt_shift_toggle",
kb_rules = "",
numlock_by_default = true,
repeat_rate = 40, -- repeats per second, Hyprland default 25
repeat_delay = 250, -- ms, Hyprland default 600
follow_mouse = 1,
sensitivity = 0, -- -1.0 .. 1.0
accel_profile = "flat", -- "adaptive" | "flat" | "custom"
touchpad = {
natural_scroll = true, -- Hyprland default false, Omarchy 4 also sets false
disable_while_typing = true, -- already the Hyprland default
clickfinger_behavior = true, -- 2-finger = right click, Omarchy 4 already sets this
tap_to_click = true, -- already the Hyprland default
scroll_factor = 0.4, -- Omarchy 4 already sets this
},
},
})
Valid layout, variant and option names:
localectl list-x11-keymap-layouts
localectl list-x11-keymap-variants fr
grep -E '^[[:space:]]*(caps|grp|compose):' /usr/share/X11/xkb/rules/evdev.lst
**Apply it.** hyprctl reload re-runs the whole Lua config, including Omarchy's /etc/vconsole.conf read:
hyprctl reload
Try a value before writing it. On 0.56 hyprctl eval takes a Lua string, which is how Omarchy's own omarchy-toggle-input-device drives the compositor:
hyprctl eval 'hl.config({ input = { kb_options = "compose:caps,caps:escape" } })'
hyprctl dispatch also takes Lua on 0.56, so a bare hyprctl dispatch <dispatcher> <args> copied from an older guide will fail to parse.
**Per-device settings.** Hyprland lowercases the libinput name and turns spaces into hyphens, so do not guess it. Print the exact strings:
hyprctl -j devices | python3 -c 'import json,sys; d=json.load(sys.stdin); [print(k["name"]) for k in d["keyboards"]]'
hyprctl -j devices | python3 -c 'import json,sys; d=json.load(sys.stdin); [print(m["name"]) for m in d["mice"]]'
Real names from a live Omarchy 4 machine: corsair-corsair-gaming-k55-rgb-keyboard, razer-razer-basilisk-v3.
hl.device({
name = "razer-razer-basilisk-v3",
sensitivity = -0.2,
accel_profile = "flat",
natural_scroll = false,
})
hl.device({
name = "corsair-corsair-gaming-k55-rgb-keyboard",
kb_layout = "us,pl,de",
})
Every input option and subcategory such as input.touchpad works inside hl.device except force_no_accel and the window-management ones (follow_mouse, follow_mouse_threshold, float_switch_override_focus, mouse_refocus, special_fallthrough). enabled, keybinds and tags exist only in hl.device.
**Switch layouts at runtime:**
hyprctl switchxkblayout corsair-corsair-gaming-k55-rgb-keyboard next
hyprctl switchxkblayout all next
hyprctl switchxkblayout current 1
current means the keyboard hyprctl devices marks main: yes, which is often not a keyboard you type on. With fcitx5 running it is hl-virtual-keyboard-fcitx5. Name the physical device, or use all.
**Omarchy 4 puts this on the bar for you.** Once kb_layout holds more than one entry the omarchy.keyboard-layout widget appears next to the clock and a click cycles the layout. It hides itself on a single-layout install, which is why you may never have seen it:
grep -n 'omarchy.keyboard-layout' ~/.config/omarchy/shell.json
omarchy-bar put omarchy.keyboard-layout --after omarchy.clock # only if it is missing
**Keybinds firing on the wrong layout.** By default binds resolve against the first kb_layout entry. Either keep a Latin layout first, which is what Omarchy does automatically, or opt into symbol-based resolution:
hl.config({ input = { resolve_binds_by_sym = true } })
**Omarchy: change the system layout so the default picks it up.** /usr/share/omarchy/default/hypr/input.lua reads XKBLAYOUT and XKBVARIANT from /etc/vconsole.conf every time the config loads, so a system-wide change is enough as long as you have not written a local override:
grep XKB /etc/vconsole.conf # record all four lines first
sudo localectl set-x11-keymap fr pc105 '' terminate:ctrl_alt_bksp
grep XKB /etc/vconsole.conf # check all four, not just the layout
hyprctl reload
Pass model, variant and options explicitly. localectl sends an empty string for every positional argument you leave off (src/locale/localectl.c, verb_set_x11_keymap), so a bare sudo localectl set-x11-keymap fr also wipes XKBMODEL and XKBOPTIONS. Omarchy's Hyprland config ignores XKBOPTIONS, but the virtual console and Xwayland do not.
**Will omarchy update overwrite your edit?** Only while the file is still stock. /usr/share/omarchy/migrations/1781485962.sh takes a sha256 of ~/.config/hypr/input.lua with the kb_layout and kb_variant lines stripped out, and copies the packaged template over it only on a match. Once you have uncommented anything the file is yours and no migration replaces it.
Verify
hyprctl getoption input:kb_layout and hyprctl getoption input:kb_options return exactly what you set, including the Omarchy options you meant to keep. hyprctl devices shows each keyboard with the expected rules: line and active keymap, and a per-device override shows only on that device. After a localectl change, grep XKB /etc/vconsole.conf still shows XKBMODEL and XKBOPTIONS, not just XKBLAYOUT. With two or more layouts, the omarchy.keyboard-layout widget appears on the bar and its label changes when you switch. Typing in a terminal produces the right characters, Caps Lock behaves as configured, and your Super keybinds still fire.
Sources
- https://wiki.hypr.land/Configuring/Basics/Variables/
- https://wiki.hypr.land/Configuring/Advanced-and-Cool/Devices/
- https://wiki.hypr.land/Configuring/Advanced-and-Cool/Using-hyprctl/
- https://wiki.archlinux.org/title/Xorg/Keyboard_configuration
- https://github.com/hyprwm/hyprland-wiki/blob/main/content/configuring/core/advanced-configuration/using-hyprctl.md
- https://github.com/omacom/omarchy/blob/quattro/default/hypr/input.lua
- https://github.com/omacom/omarchy/blob/quattro/config/hypr/input.lua
- https://github.com/omacom/omarchy/blob/quattro/migrations/1781485962.sh
- https://github.com/omacom/omarchy/blob/quattro/shell/plugins/bar/widgets/KeyboardLayout.qml
- https://github.com/systemd/systemd/blob/main/src/locale/localectl.c