Fix the whole desktop freezing when you press a custom Lua keybind
The binds wiki page opens with a warning that matches the record: Lua callbacks run on the compositor event loop, io.popen, network I/O, clipboard tools (wl-paste, xclip) and sleeps must be avoided, hl.dsp.exec_cmd should be preferred, waits should be bounded with timeout, and a hung call freezes input and the whole desktop. Hyprland v0.56.2 source adds one detail. Keybind callbacks run under guardedPCall with LUA_TIMEOUT_KEYBIND_CALLBACK_MS = 100, but the watchdog is a Lua instruction-count hook, so it can stop a pure-Lua loop and cannot interrupt a blocking C call such as an io.popen read. The record's advice therefore stands. The Omarchy claim was checked in helpers.lua, where o.bind wraps a string dispatcher in hl.dsp.exec_cmd. The explanation that wl-paste waits on the blocked compositor is the auditor's own reasoning. It is consistent with Wayland data transfer going through the compositor, but no cited source states it. Not exercised: no freeze was reproduced here.
Symptom
Pressing a custom keybinding freezes everything: the mouse pointer and keyboard stop responding and no window redraws, for seconds or until something is killed. The bind uses a Lua function that calls io.popen(...), os.execute(...), wl-paste, curl or a sleep.
Cause
Lua bind callbacks run on the compositor's event loop. A blocking call inside one (io.popen waiting on a slow or hung command, clipboard tools such as wl-paste, network I/O, sleeps) stops Hyprland from processing input and rendering until it returns. wl-paste is a common trap because it can wait on the compositor that is itself blocked.
Fix
Run external work outside the callback with the exec dispatcher, which spawns it asynchronously:
-- blocks the compositor: do not do this
-- hl.bind("SUPER + V", function() local p = io.popen("wl-paste") ... end)
-- runs outside the event loop
hl.bind("SUPER + V", hl.dsp.exec_cmd("sh -c 'wl-paste | my-filter | wl-copy'"))
On Omarchy, o.bind(keys, description, "command") already wraps a string in hl.dsp.exec_cmd.
If a bind really must read a result back into Lua, bound the wait so a hang cannot last:
local p = io.popen("timeout 1 my-probe 2>/dev/null")
To recover from a freeze already in progress, kill the hung child from another session, for example over SSH (pkill -x wl-paste). The callback then returns and input resumes.
Verify
Press the rewritten bind repeatedly. The pointer keeps moving during the command and the command's effect still happens.