OPINIONATED OMARCHY
TROUBLESHOOTING CORPUS
790
RECORDS
790
AUDITED
0
UNCHECKED
2388
SOURCES
LIVE
hyprland-config high very-common DISPUTE

Work out whether your Hyprland config should be hyprlang or Lua

hyprlandarchendeavouroscachyosmanjaroomarchywayland
CORRECTED An auditor found the fix wrong or incomplete and rewrote it.
AUDIT NOTE

Checked on this workstation (omarchy 4.0.2-1, omarchy-settings 4.0.2-1, hyprland 0.56.2-1) and against the Hyprland v0.56.2 source. The precedence claim is CONFIRMED twice over: Jeremy::getMainConfigPath() returns the .lua path if Hyprutils::Path::findConfig(..., "lua") finds one and only falls through to .conf otherwise, and the Lua announcement says the same in prose. Config::initConfigManager() then picks Lua::CConfigManager or Legacy::CConfigManager from the extension. The path is cached in a function-local static and only Config::Supplementary::Jeremy::flushCachedCfgPath() clears it, which reloadRequest() in src/debug/HyprCtl.cpp calls only when the request ends with full-reset, so the record's claim that plain hyprctl reload will not switch engines is CONFIRMED from source. The wiki text the danger paraphrases is verbatim: "full-reset should not be used unless really necessary." Four things were wrong. First, the version story: the record says "0.55 (May 2026)" and "guaranteed for a few releases", where the announcement says the change landed 26 April 2026 and that hyprlang lasts "1 - 2 releases starting from 0.55", which matters because 0.56 shipped on 20 July 2026 and the runway is nearly gone. Second, and this is the Omarchy defect, the record lists omarchy in applies_to and then hands an Omarchy user mv ~/.config/hypr/hyprland.lua ~/.config/hypr/hyprland.lua.disabled: there is no hyprland.conf in ~/.config/hypr on this machine, /usr/share/omarchy/config/hypr/ ships hyprland.lua and no .conf, and with neither file present initConfigManager() generates a stock default, so that command destroys the Omarchy desktop rather than reverting it. omarchy-refresh-hyprland is the supported restore and was read at /usr/share/omarchy/bin/omarchy-refresh-hyprland. Third, the diagnosis step was ls, when hyprctl systeminfo reports configProvider: lua directly (confirmed on this machine) and Hyprland logs [cfg] Using lua config found at ... (confirmed in this session's $XDG_RUNTIME_DIR/hypr/*/hyprland.log). Fourth, the verify used hyprctl getoption general:gaps_in, which on 0.56.2 prints css gap data: 5 5 5 5 rather than a value (confirmed by running it), so it was swapped for general:border_size, which printed int: 2. The recovery gap the fix now closes is that a reader whose config does not load has no keybindings: src/config/lua/Emergency.hpp binds SUPER+Q to the first installed terminal, SUPER+R to hyprland-run and SUPER+M to exit, tripped in CConfigManager::reload() when there are errors and no binds. NOT exercised: nothing was written under ~/.config/hypr, no config was renamed, full-reset was never run and neither was omarchy-refresh-hyprland, so the recovery paths are read from source and from the shipped scripts rather than performed. One plain hyprctl reload fired accidentally while probing argument handling and re-read the unchanged config with no effect.

The cause above was rewritten on 2026-09-13 to match this note; the fix was corrected by the audit itself.
RISK

hyprctl reload full-reset recreates the entire config context. The wiki says full-reset should not be used unless really necessary. Expect a visible flicker and layer-shell clients (bars, wallpapers) to re-init.

On Omarchy 4 the bigger risk is the hyprlang branch itself. There is no ~/.config/hypr/hyprland.conf to fall back to, so moving hyprland.lua aside makes Hyprland write a stock default over it and you lose every Omarchy binding, the bar and the theme in one keystroke. Restore with omarchy-refresh-hyprland, which backs up what it replaces as <file>.bak.<epoch>.

Symptom

Edits to ~/.config/hypr/hyprland.conf do nothing at all: no errors, no effect. Or the opposite: the wiki examples you copy (hl.config({...}), hl.bind(...)) are all rejected as syntax errors by your Hyprland.

Cause

Hyprland 0.55 deprecated hyprlang in favour of Lua and rewrote the whole wiki for Lua. The change landed on git on 26 April 2026 and shipped in 0.55 on 9 May 2026. Hyprland decides once, at startup, in Jeremy::getMainConfigPath(): if ~/.config/hypr/hyprland.lua exists it is loaded exclusively and hyprland.conf is ignored entirely, if it does not exist hyprland.conf is loaded by the legacy hyprlang manager, and if neither exists Hyprland generates a default hyprland.lua. So a leftover hyprland.lua silently orphans your .conf, and copying Lua snippets into a .conf (or hyprlang into a .lua) fails wholesale. The only record of which engine won is a DEBUG line in Hyprland's own log, so nothing tells you on screen. Upstream says hyprlang is supported for 1 to 2 releases starting from 0.55 and is then dropped, and no new config features are added to it. Omarchy 4 is already past that decision: it ships ~/.config/hypr/hyprland.lua from omarchy-settings and ships no hyprland.conf, so on Omarchy there is nothing to fall back to and removing the Lua file costs you the whole desktop rather than reverting it.

Fix

Do not guess from the file names. Ask the running compositor which engine it loaded.


hyprctl systeminfo | grep configProvider     # "lua" or "hyprlang"
hyprctl version | head -1                    # Lua needs >= 0.55
ls -l ~/.config/hypr/hyprland.lua ~/.config/hypr/hyprland.conf

Hyprland also records the decision in its own log at startup, which is the only place it is written down:


grep '\[cfg\]' "$XDG_RUNTIME_DIR/hypr/$HYPRLAND_INSTANCE_SIGNATURE/hyprland.log"
# [cfg] Using lua config found at /home/you/.config/hypr/hyprland.lua
# or
# [cfg] Lua config not found, using legacy config at /home/you/.config/hypr/hyprland.conf

**On Omarchy 4, you are on Lua and there is no hyprlang branch.** Omarchy ships ~/.config/hypr/hyprland.lua from /usr/share/omarchy/config/hypr/hyprland.lua (owned by omarchy-settings) and ships no hyprland.conf at all. Renaming hyprland.lua away does not fall back to anything: Hyprland finds no config, writes a stock default hyprland.lua, and you lose every Omarchy default in one step, including the bar, the theme, SUPER + SPACE and SUPER + RETURN. If you have already broken your config, restore the shipped files instead of hand editing. It backs up what it replaces as <file>.bak.<epoch>:


omarchy-refresh-hyprland          # restores hyprland.lua, bindings.lua, monitors.lua,
                                  # input.lua, looknfeel.lua, autostart.lua, .luarc.json

Run that from a login shell. OMARCHY_PATH is unset in a non-interactive ssh, so over ssh use ssh host 'bash -lc omarchy-refresh-hyprland'.

**On plain Arch or another distro, to stay on hyprlang** you need an existing hyprland.conf to fall back to. Check it is there first, because if both files are missing Hyprland writes a fresh default hyprland.lua and you are back on Lua:


test -f ~/.config/hypr/hyprland.conf && mv ~/.config/hypr/hyprland.lua ~/.config/hypr/hyprland.lua.disabled
hyprctl reload full-reset

The current wiki no longer documents hyprlang. The archived 0.54 docs are at https://wiki.hypr.land/0.54.0/. This is a short runway: upstream says hyprlang is supported for 1 to 2 releases from 0.55 and then dropped, and 0.56 is already out.

**To move to Lua**, create ~/.config/hypr/hyprland.lua. Split files with require(), not source =:


-- ~/.config/hypr/hyprland.lua
require("monitors")          -- ~/.config/hypr/monitors.lua
require("awesomeconf/keybinds")
hl.config({ general = { gaps_in = 5, gaps_out = 10, border_size = 2 } })
hl.bind("SUPER + Return", hl.dsp.exec_cmd("kitty"))

hyprctl reload alone will NOT switch engines. The resolved config path is cached for the life of the compositor and only full-reset flushes it:


hyprctl reload full-reset

**If the config errors and you are left with no keybindings at all**, Hyprland 0.55+ trips emergency mode and binds three keys for you, and prints them on screen:


SUPER + Q   launch the first of kitty, alacritty, foot, wezterm, gnome-terminal, xterm
SUPER + R   hyprland-run
SUPER + M   exit Hyprland

Emergency mode only trips when the config raised an error AND no binds were registered. If your config half loaded you may have neither. A TTY on CTRL + ALT + F2 always works.

Verify

hyprctl systeminfo | grep configProvider reports lua or hyprlang and is the definitive answer. Then hyprctl getoption general:border_size reflects the value from the file you just edited, and a deliberate typo in that file shows up in hyprctl configerrors. Use border_size rather than general:gaps_in, which on 0.56 prints css gap data: 5 5 5 5 instead of a single number.

Sources

hyprlang-deprecated-lua-config-not-loading