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

hl.env() variables never reach systemd user services or D-Bus-activated apps

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

Checked against Hyprland source at tag v0.56.2 and against this workstation (omarchy 4.0.2-1, hyprland 0.56.2-1, uwsm 0.26.7-1). The seven-name allowlist claim is exact: src/Compositor.cpp at v0.56.2 contains systemctl --user import-environment DISPLAY WAYLAND_DISPLAY HYPRLAND_INSTANCE_SIGNATURE XDG_CURRENT_DESKTOP QT_QPA_PLATFORMTHEME PATH XDG_DATA_DIRS and the six-name dbus-update-activation-environment --systemd ... line, guarded by m_aqBackend->hasSession() and HYPRLAND_NO_SD_VARS. Two defects, both Omarchy-4 specialisation failures of exactly the kind this re-audit looks for. First, hl.env() takes a third boolean argument on 0.56.2 that makes Hyprland run systemctl --user import-environment '<name>' and dbus-update-activation-environment --systemd '<name>' itself, confirmed in src/config/lua/bindings/LuaBindingsConfigRules.cpp at v0.56.2, and the record never mentions it while recommending the manual commands. Second, and worse, the symptom is usually absent on a stock Omarchy 4 because /usr/share/omarchy/default/hypr/autostart.lua already runs systemctl --user import-environment $(env | cut -d'=' -f 1) and dbus-update-activation-environment --systemd --all on hyprland.start. Confirmed on this machine: systemctl --user show-environment carries GDK_BACKEND, OZONE_PLATFORM, ELECTRON_OZONE_PLATFORM_HINT, XCURSOR_SIZE, HYPRCURSOR_SIZE, XCOMPOSEFILE, OMARCHY_PATH, QT_QPA_PLATFORM, XDG_SESSION_DESKTOP and XDG_MENU_PREFIX, all set by hl.env() in /usr/share/omarchy/default/hypr/envs.lua and none of them in Hyprland's allowlist. That makes the record's step C actively wrong advice on Omarchy, since it tells the reader to add to ~/.config/hypr/autostart.lua a command Omarchy already runs. Step D was also stale: the current wiki page content/configuring/core/environment-variables.md is 68 lines and contains no uwsm guidance at all, and Omarchy's own /usr/share/uwsm/env.d/10-omarchy names ~/.config/uwsm/env.d/* as the preferred override point, not ~/.config/uwsm/env. The uwsm file names themselves still hold: uwsm 0.26.7's README line 112 lists uwsm/env, uwsm/env.d/*, uwsm/env-${desktop} and uwsm/env-${desktop}.d/*, and ${desktop} is hyprland because /usr/share/wayland-sessions/hyprland-uwsm.desktop runs uwsm start -e -D Hyprland hyprland.desktop. The environment.d mechanism and the /etc/environment danger both held: the wiki carries that warning verbatim, and ~/.config/environment.d/omarchy-firefox-wayland.conf on this machine puts MOZ_ENABLE_WAYLAND into the user manager. I did NOT exercise anything: per the job's safety constraint I ran no systemctl --user import-environment, no dbus-update-activation-environment, started or restarted no unit, and wrote no config, so the corrected fix's write steps are read from source and from Omarchy's own shipped files rather than executed. I also did not test a lingering or ssh-started user manager.

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

Do not put Wayland-specific variables in /etc/environment. That file is read by every session on the machine, including Xorg ones and display managers, and setting things like GDK_BACKEND=wayland there will break logins into non-Wayland sessions.

Symptom

A variable set with hl.env("FOO", "bar") is visible in a terminal you launched from a keybind, but systemctl --user show-environment does not list it. Downstream: the theme or cursor is right in apps you launch by hotkey and wrong in anything started by a .service or by .desktop D-Bus activation, a --user service you wrote cannot find the variable, flatpak run apps ignore your env, and portal-launched helpers behave as though the variable does not exist.

On a stock Omarchy 4 you will usually not see this at all, because Omarchy's own autostart imports the entire session environment into the systemd user manager. Omarchy users hit the narrower cases instead: a variable set after hyprland.start has already run, a user manager started by ssh or by lingering, or a unit that was already running when the variable appeared.

Cause

hl.env("FOO", "bar") calls setenv() inside the compositor's own process, so the variable is inherited only by processes Hyprland forks after that line runs. Confirmed in Hyprland 0.56.2 in src/config/lua/bindings/LuaBindingsConfigRules.cpp, where the binding body is a plain setenv(name.c_str(), value.c_str(), 1).

Separately, Hyprland pushes a fixed seven-name allowlist into the systemd user manager and the D-Bus activation environment. From src/Compositor.cpp at tag v0.56.2, in CCompositor::startCompositor():


systemctl --user import-environment DISPLAY WAYLAND_DISPLAY HYPRLAND_INSTANCE_SIGNATURE XDG_CURRENT_DESKTOP QT_QPA_PLATFORMTHEME PATH XDG_DATA_DIRS
dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP HYPRLAND_INSTANCE_SIGNATURE QT_QPA_PLATFORMTHEME PATH XDG_DATA_DIRS

It runs only when the backend has a session and HYPRLAND_NO_SD_VARS is unset. Anything outside that list is invisible to user units and to D-Bus-activated apps, and anything already running when Hyprland starts never sees it.

Two things change that picture on Hyprland 0.56 and on Omarchy 4.

  1. hl.env() takes a third boolean argument that does the push for you. With hl.env("XCURSOR_THEME", "Bibata-Modern-Classic", true) Hyprland runs systemctl --user import-environment 'XCURSOR_THEME' followed by dbus-update-activation-environment --systemd 'XCURSOR_THEME' for that single name. Same file, same version.
  1. Omarchy 4 already imports the whole session environment. /usr/share/omarchy/default/hypr/autostart.lua runs this on hyprland.start, before it launches the shell and the session services:

hl.exec_cmd("systemctl --user import-environment $(env | cut -d'=' -f 1)")
hl.exec_cmd("dbus-update-activation-environment --systemd --all")

Measured on this workstation (omarchy 4.0.2-1, hyprland 0.56.2-1): systemctl --user show-environment carries GDK_BACKEND, OZONE_PLATFORM, ELECTRON_OZONE_PLATFORM_HINT, XCURSOR_SIZE, HYPRCURSOR_SIZE, XCOMPOSEFILE, OMARCHY_PATH, QT_QPA_PLATFORM, XDG_SESSION_DESKTOP and XDG_MENU_PREFIX. Not one of those is in Hyprland's allowlist, and every one of them is set by hl.env() in /usr/share/omarchy/default/hypr/envs.lua.

So on Omarchy 4 the remaining failure cases are narrower: a variable that first appears after that import has already run, a systemd user manager started by ssh or by lingering rather than by the graphical session (it never saw the session environment at all), and units that were already running when the variable arrived.

Fix

Pick the mechanism that matches who needs the variable.

**A. Anything Hyprland launches (keybinds, autostart, exec rules).** hl.env() is correct and sufficient:


hl.env("GTK_THEME", "Adwaita:dark")
-- reference an existing variable with os.getenv, not shell $ syntax:
hl.env("SSH_AUTH_SOCK", os.getenv("XDG_RUNTIME_DIR") .. "/ssh-agent.socket")

**B. One variable that also has to reach systemd and D-Bus: use the third argument.** Hyprland 0.56 accepts a boolean third argument on hl.env() and does the push itself:


hl.env("XCURSOR_THEME", "Bibata-Modern-Classic", true)

That runs systemctl --user import-environment 'XCURSOR_THEME' and dbus-update-activation-environment --systemd 'XCURSOR_THEME'. Prefer this over calling either command by hand. Like every push, it affects units started after it runs, not units already running.

**C. systemd --user services and D-Bus-activated apps, durable across everything: environment.d.** The user manager parses these at start, so they apply even to a manager that never saw a graphical session:


mkdir -p ~/.config/environment.d
cat > ~/.config/environment.d/10-wayland.conf <<'EOF'
XCURSOR_THEME=Bibata-Modern-Classic
XCURSOR_SIZE=24
ELECTRON_OZONE_PLATFORM_HINT=auto
MOZ_ENABLE_WAYLAND=1
EOF

Log out and back in. The user manager only re-reads these on start, so systemctl --user daemon-reload will not pick them up. Confirmed on this machine: ~/.config/environment.d/omarchy-firefox-wayland.conf contains MOZ_ENABLE_WAYLAND=1 and that variable is in systemctl --user show-environment.

**D. On Omarchy 4, check before you fix anything.** Omarchy's /usr/share/omarchy/default/hypr/autostart.lua already imports the whole environment into the user manager on hyprland.start, so the variable is very likely there already:


systemctl --user show-environment | grep XCURSOR_THEME

If it is there, you have no problem to fix. If you want to change an Omarchy session default, the supported override point is a uwsm drop-in, which /usr/share/uwsm/env.d/10-omarchy names in its own comments:


mkdir -p ~/.config/uwsm/env.d
cat > ~/.config/uwsm/env.d/50-mine <<'EOF'
export XCURSOR_THEME=Bibata-Modern-Classic
EOF

Log out and back in. Verified by the same route on omarchy 4.0.2-1: TERMINAL=xdg-terminal-exec and EDITOR=omarchy-launch-editor --inline are set only by /usr/share/omarchy/default/uwsm/default, which /usr/share/uwsm/env.d/10-omarchy sources, and both appear in systemctl --user show-environment.

**E. uwsm sessions generally.** uwsm 0.26.7 sources uwsm/env, uwsm/env.d/*, uwsm/env-${desktop} and uwsm/env-${desktop}.d/* from each config directory, one export KEY=VAL per line. On Omarchy the session entry is uwsm start -e -D Hyprland hyprland.desktop, so ${desktop} is hyprland and ~/.config/uwsm/env-hyprland is the per-compositor file. Use it for HYPR* and AQ_*:


# ~/.config/uwsm/env-hyprland
export AQ_DRM_DEVICES="/dev/dri/amd-igpu:/dev/dri/card1"

The wiki advice to keep env vars out of hyprland.lua entirely under uwsm does not match what Omarchy ships. Omarchy sets about fifteen variables with hl.env() in /usr/share/omarchy/default/hypr/envs.lua. Treat the uwsm files as the place for your overrides, not as a rule that hl.env() is wrong.

**F. Push what is already in the session, right now.** Useful for a one-off, or for a portal that came up before your variables existed:


dbus-update-activation-environment --systemd --all
systemctl --user import-environment QT_QPA_PLATFORMTHEME XCURSOR_THEME XCURSOR_SIZE

On plain Hyprland, run it from your autostart so it happens every session. Hyprland's documented hook is the start event, not a bare top-level dispatch, which would re-run on every config reload:


hl.on("hyprland.start", function()
  hl.exec_cmd("dbus-update-activation-environment --systemd --all")
end)

Do not add this on Omarchy 4. /usr/share/omarchy/default/hypr/autostart.lua already runs both commands, and your ~/.config/hypr/autostart.lua is loaded in addition to it, so you would only be running them twice.

This affects units started after it runs, not units already running. Restart the affected service.

If you use dbus-broker rather than the reference dbus daemon, dbus-update-activation-environment is redundant, because dbus-broker already reuses systemd's activation environment.

Verify

systemctl --user show-environment | grep XCURSOR_THEME prints your value, and systemctl --user restart <yourservice> then systemctl --user show <yourservice> -p Environment shows it reaching the unit.

Sources

hl-env-not-visible-to-systemd-user-services