Fix keybindings that launch apps failing after setting PATH with hl.env
The core is confirmed. hlEnv in v0.56.2 LuaBindingsConfigRules.cpp passes the value through CLuaConfigString::parse, which does no expansion, then setenv(). The wiki environment-variables page says to use os.getenv(). Executor.cpp spawns every command with execl("/bin/sh", "/bin/sh", "-c", ...), so the shell searches the bogus PATH. Omarchy's default/hypr/envs.lua rebuilds PATH from os.getenv("PATH"), so removing the line and reloading leaves '/usr/share/omarchy/bin:$HOME/.local/bin:$PATH' with /usr/bin still missing. That is why a restart is needed. The claim that the broken PATH 'is copied into the systemd user manager' is very likely wrong. Both Hyprland's own first-launch import (Executor.cpp line 34) and Omarchy's autostart.lua systemctl --user import-environment $(env | cut ...) run through /bin/sh with that same PATH, so systemctl, env and cut are not found and the import never runs. The user manager keeps the PATH uwsm gave it. This is reasoned from source and was not reproduced. The danger built on that claim was rewritten. The title said every keybinding fails, but binds whose action is a dispatcher such as hl.dsp.window.close() never spawn a process and still work, so the title was narrowed. Also missing from the fix: on Omarchy 4, ~/.local/bin is already on the session PATH. /usr/share/omarchy/default/bash/env-bootstrap, sourced by /usr/share/uwsm/env.d/10-omarchy, appends it, and systemctl --user show-environment here shows it. uwsm env.d sourcing was confirmed in man uwsm (0.26.7-1) and the uwsm README. Issue omacom/omarchy#6977 is about envs.lua prepending /usr/share/omarchy/bin, which hides some omarchy subcommands. It does not concern literal $ in hl.env, so it was removed from sources.
Do the fix from a TTY (CTRL+ALT+F3), because the graphical session cannot launch a terminal. Removing the line and reloading does not repair the running compositor's PATH. Reboot, or log out and back in, before judging whether the fix worked.
Symptom
After I added hl.env("PATH", "$HOME/.local/bin:$PATH") (or ~/bin:$PATH) to my Hyprland Lua config, nothing launches from a keybinding: SUPER+RETURN, SUPER+SPACE and every app bind do nothing. Terminals I already had open still work. Another version: my PATH gets longer every time I save the config, with the same directory repeated many times.
Cause
hl.env(name, value) in Hyprland 0.56.2 passes the string straight to setenv() in the compositor process (hlEnv in src/config/lua/bindings/LuaBindingsConfigRules.cpp). Lua does no shell expansion, so $HOME, $PATH and ~ stay as literal text and PATH becomes the single bogus entry $HOME/.local/bin:$PATH. Hyprland runs every command bind through /bin/sh -c (src/config/supplementary/executor/Executor.cpp), and that shell searches the bogus PATH, so omarchy-launch-terminal, omarchy-menu, uwsm-app and the rest are not found. Binds whose action is a dispatcher, such as closing or moving a window, spawn nothing and keep working. The wiki says to read existing variables with os.getenv() instead.
On Omarchy 4, fixing the line and reloading is not enough. default/hypr/envs.lua rebuilds PATH from the compositor's current, already broken PATH on each load, which leaves /usr/share/omarchy/bin:$HOME/.local/bin:$PATH with /usr/bin still missing. The compositor has to be restarted from a clean environment.
The systemd user manager is very likely not affected. Hyprland's own first-launch systemctl --user import-environment ... PATH and Omarchy's autostart.lua import both run through /bin/sh with the same broken PATH, so systemctl itself is not found and the import never happens. That was read from source and not reproduced.
The growing PATH has a related root. The config is re-run on every reload, so hl.env("PATH", dir .. ":" .. os.getenv("PATH")) prepends again each time. Omarchy's envs.lua avoids that by removing its own entry before prepending.
Fix
**1. Recover.** Switch to a TTY with CTRL+ALT+F3, log in, and remove or fix the line in ~/.config/hypr/*.lua:
grep -n 'hl.env("PATH"' ~/.config/hypr/*.lua
Then reboot, so the compositor starts from a clean environment:
systemctl reboot
**2a. Omarchy 4: you may not need anything.** ~/.local/bin is already on the session PATH. Omarchy's /usr/share/omarchy/default/bash/env-bootstrap, which uwsm sources through /usr/share/uwsm/env.d/10-omarchy, appends it. Check with:
systemctl --user show-environment | grep ^PATH= | tr ':' '\n' | grep -x "$HOME/.local/bin"
For any other directory, or to put ~/.local/bin ahead of /usr/bin, add it through uwsm, not hl.env. uwsm sources ~/.config/uwsm/env and ~/.config/uwsm/env.d/* as shell before it starts Hyprland, so $HOME and $PATH expand. 10-omarchy names ~/.config/uwsm/env.d/ as the preferred place for overrides:
mkdir -p ~/.config/uwsm/env.d
cat > ~/.config/uwsm/env.d/10-path.sh <<'EOF'
export PATH="$HOME/bin:$PATH"
EOF
Log out and back in. The file is read only at session start.
**2b. Plain Arch, or if you need it in the Hyprland config:** build the value with os.getenv and guard against repeats:
local dir = os.getenv("HOME") .. "/.local/bin"
local path = os.getenv("PATH") or "/usr/local/bin:/usr/bin"
if not (":" .. path .. ":"):find(":" .. dir .. ":", 1, true) then
hl.env("PATH", dir .. ":" .. path)
end
The same applies to any variable. hl.env("SSH_AUTH_SOCK", os.getenv("XDG_RUNTIME_DIR") .. "/ssh-agent.socket") works and hl.env("SSH_AUTH_SOCK", "$XDG_RUNTIME_DIR/ssh-agent.socket") does not.
Verify
In a new terminal opened with SUPER+RETURN, echo "$PATH" | tr ':' '\n' shows real directories with no literal $ and no repeats, and systemctl --user show-environment | grep ^PATH= matches. SUPER+SPACE opens the menu. The literal-string behaviour was read from the 0.56.2 hlEnv source and the uwsm file locations from man uwsm (uwsm 0.26.7). The breakage itself was not reproduced.
Sources
- https://wiki.hypr.land/configuring/core/environment-variables/
- https://github.com/hyprwm/Hyprland/blob/v0.56.2/src/config/lua/bindings/LuaBindingsConfigRules.cpp
- https://github.com/omacom/omarchy/blob/quattro/default/hypr/envs.lua
- https://github.com/omacom/omarchy/blob/quattro/default/hypr/autostart.lua
- https://github.com/Vladimir-csp/uwsm/blob/master/README.md
- https://github.com/hyprwm/Hyprland/blob/v0.56.2/src/config/supplementary/executor/Executor.cpp
- https://github.com/omacom/omarchy/blob/quattro/default/bash/env-bootstrap