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

Set environment variables where a uwsm session will actually see them

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

Re-audited against this workstation (omarchy 4.0.2-1, omarchy-settings 4.0.2-1, hyprland 0.56.2-1, uwsm 0.26.7-1) and against upstream source. The record's fix files are real and its danger is a faithful reading of the Arch wiki, which at Hyprland says verbatim not to put environment variables in hyprland.lua under uwsm and names ~/.config/uwsm/env and ~/.config/uwsm/env-hyprland. The cause is wrong for Omarchy 4. It claims variables set in the compositor config never reach the systemd user session. On this machine systemctl --user show-environment carries GDK_SCALE, XCOMPOSEFILE, OMARCHY_PATH, QT_QPA_PLATFORMTHEME and the whole GUM_* block, and the environ of all three running xdg-desktop-portal processes (pids 2556, 2701, 2756) carries the same names, yet none of them is in Hyprland's own import list. I read that list in src/Compositor.cpp at v0.56.2: it is exactly seven names (DISPLAY WAYLAND_DISPLAY HYPRLAND_INSTANCE_SIGNATURE XDG_CURRENT_DESKTOP QT_QPA_PLATFORMTHEME PATH XDG_DATA_DIRS). The variables get there because /usr/share/omarchy/default/hypr/autostart.lua runs systemctl --user import-environment $(env | cut -d'=' -f 1) and dbus-update-activation-environment --systemd --all on hyprland.start, so the generic uwsm advice does not transfer to Omarchy unchanged and the record was presenting a symptom that a stock Omarchy install mostly does not have.

I replaced the cause and fix with the three-store model and an ordered decision procedure covering all four places a reader might put a variable, because this record is the one other records should point at. Three mechanisms were added, each confirmed at source rather than assumed. ~/.config/hypr/envs.lua is never loaded: both /usr/share/omarchy/config/hypr/hyprland.lua and the live ~/.config/hypr/hyprland.lua require exactly five user modules and none is hypr.envs, so hl.env() lines there are a silent no-op. hl.env takes a third boolean on 0.56.2 which makes Hyprland run systemctl --user import-environment '<name>' and dbus-update-activation-environment --systemd '<name>' itself, read in src/config/lua/bindings/LuaBindingsConfigRules.cpp around line 525. And hyprland.start and config.reloaded are distinct events in src/config/lua/LuaEventHandler.cpp (lines 151 and 165), so a reload re-applies hl.env inside Hyprland but does not refresh the systemd or D-Bus stores, which is the residual failure the record should have described.

Three smaller corrections. The record framed ~/.config/uwsm/env as the Arch path and ~/.config/uwsm/env.d/20-user as the Omarchy one. That split is false: /usr/lib/uwsm/prepare-env.sh sources uwsm/env, uwsm/env.d/*, uwsm/env-${desktop} and uwsm/env-${desktop}.d/* from every rung of $XDG_CONFIG_HOME:$XDG_CONFIG_DIRS:$XDG_DATA_DIRS, so all four shapes work identically on both, and uwsm's own README says the same at the "where to put a user-level var" summary. The record called GDK_SCALE in monitors.lua an exception, when it is the general Omarchy pattern, and upstream ships local omarchy_gdk_scale = 2 there, which I confirmed on quattro. The record never mentioned ~/.config/environment.d/, which is the correct answer for a systemd-user-only variable and which Omarchy itself uses at /usr/share/omarchy/default/environment.d/10-omarchy-fcitx.conf. I added the D-Bus activation environment as a named separate store and put a read of it into verify, since the record previously checked only the systemd store. I also rewrote danger to drop an em dash. Its content is unchanged and still matches the wiki.

Severity and frequency left at medium / common. The consequence is a variable that silently does nothing, not a broken machine, and the question of where to put one is asked constantly even though the stock install absorbs most cases.

Not exercised: I changed nothing and logged out of nothing, so the claim that a fresh uwsm env file is picked up at the next login is from prepare-env.sh and the uwsm README rather than from a session restart on this box. I did not run systemctl --user import-environment, dbus-update-activation-environment, hyprctl reload or any hyprctl keyword. The env-hyprland filename is derived from prepare-env.sh lowercasing XDG_CURRENT_DESKTOP, which is Hyprland here, rather than from a file that exists on this machine. ~/.config/uwsm/ does not exist on this install, so the user-side uwsm paths are documented rather than observed in use.

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

Do not bind hl.dsp.exit() and do not kill the Hyprland process directly under uwsm. Either one bypasses the normal shutdown of the session units. Use uwsm stop or loginctl terminate-user "" instead.


hl.bind("SUPER + M", hl.dsp.exec_cmd("uwsm stop"))

Symptom

You add env = GDK_SCALE,2 or an export to your Hyprland config, reload, and nothing changes. Apps launched from the app launcher or from systemd user services never see the variable, though a terminal you open from a keybind sometimes does.

Cause

Omarchy 4 keeps three separate environment stores, and a variable is only seen by the programs whose store it reached.

  1. The Hyprland process environment. hl.env("NAME", "VALUE") in a loaded Lua file sets it here, and every client Hyprland itself spawns inherits it.
  2. The systemd user manager environment, which starts user services and anything launched through uwsm app. Read it with systemctl --user show-environment.
  3. The D-Bus activation environment, which starts D-Bus activated services such as the xdg-desktop-portal processes. It is a different store from the systemd one, and that is why a portal or a user service can see a different environment from a terminal.

Generic uwsm advice, including the Arch wiki's Hyprland page, says not to put environment variables in hyprland.lua at all. That advice is written for a bare Hyprland plus uwsm install, where Hyprland pushes only seven fixed names into the other two stores (DISPLAY WAYLAND_DISPLAY HYPRLAND_INSTANCE_SIGNATURE XDG_CURRENT_DESKTOP QT_QPA_PLATFORMTHEME PATH XDG_DATA_DIRS, in src/Compositor.cpp), so anything else set with hl.env would stop at store 1.

Omarchy 4 closes that gap and the advice therefore does not transfer unchanged. /usr/share/omarchy/default/hypr/autostart.lua runs systemctl --user import-environment $(env | cut -d'=' -f 1) and dbus-update-activation-environment --systemd --all on the hyprland.start event, so on a stock install a variable set with hl.env reaches all three stores. Omarchy relies on this for its own defaults in /usr/share/omarchy/default/hypr/envs.lua.

Three things still produce the symptom:

  • The import fires on hyprland.start only, never on config.reloaded. A variable added after login reaches Hyprland's own newly spawned children after a reload, but the systemd and D-Bus stores keep the old value until the next login.
  • ~/.config/hypr/envs.lua is never loaded. ~/.config/hypr/hyprland.lua requires exactly five user modules: hypr.monitors, hypr.input, hypr.bindings, hypr.looknfeel and hypr.autostart. There is no hypr.envs, so hl.env() lines placed in envs.lua are a silent no-op.
  • Running systemctl --user import-environment NAME by hand from an already open terminal imports that terminal's value, which is the value from before the edit.

Fix

Pick the location by who has to see the variable. The first match wins.

**1. Everything in the graphical session, including systemd user services and D-Bus activated services.** Use a uwsm env file. This is the most robust choice on both Omarchy and plain Arch, and it is what Omarchy's own /usr/share/uwsm/env.d/10-omarchy points users at.


# ~/.config/uwsm/env.d/20-user     (create ~/.config/uwsm/env.d first)
# or ~/.config/uwsm/env            for a single file
export QT_AUTO_SCREEN_SCALE_FACTOR=1
export QT_ENABLE_HIGHDPI_SCALING=1
export GDK_DPI_SCALE=1

uwsm sources uwsm/env, uwsm/env.d/*, uwsm/env-${desktop} and uwsm/env-${desktop}.d/* from every directory in $XDG_CONFIG_HOME:$XDG_CONFIG_DIRS:$XDG_DATA_DIRS, so both file shapes work on Arch and on Omarchy. They are POSIX shell, one export KEY=VALUE per line. The Arch wiki asks for no comments in them.

**2. Hyprland and Aquamarine only** (HYPR*, AQ_*). Keep these out of the common file so another compositor does not inherit them.


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

**3. The systemd user manager, including sessions that are not graphical.**


# ~/.config/environment.d/50-user.conf     KEY=VALUE, no `export`, no shell
GDK_DPI_SCALE=1

This is read by the user manager at start, so it reaches user services and anything it activates. It does not reach a login shell or a plain ssh command. Omarchy uses this path itself for input method variables in /usr/share/omarchy/default/environment.d/10-omarchy-fcitx.conf.

**4. Terminals and shell scripts only.** ~/.bashrc, or ~/.profile for login shells. Nothing graphical that was already running will see it.

**On Omarchy specifically**, hl.env() in one of the five loaded user modules also works, because default/hypr/autostart.lua imports the whole environment into systemd and D-Bus at session start. Omarchy's own display tooling uses this for GDK_SCALE in ~/.config/hypr/monitors.lua:


local omarchy_gdk_scale = 2
hl.env("GDK_SCALE", tostring(omarchy_gdk_scale))

If you use hl.env for a variable of your own and want it pushed to the other two stores without waiting for the next login, pass the third argument, which Hyprland 0.56 added. It makes Hyprland run systemctl --user import-environment and dbus-update-activation-environment --systemd for that one name:


hl.env("MY_VAR", "1", true)

**Do not use ~/.config/hypr/envs.lua.** Nothing loads it. Put hl.env() lines in one of the five modules hyprland.lua actually requires, or better, in a uwsm env file.

Whichever you pick, **log out and back in** with uwsm stop. A hyprctl reload re-runs hl.env inside Hyprland but does not refresh the systemd or D-Bus stores, because Omarchy's import is bound to hyprland.start and not to config.reloaded.

Verify

Check all three stores, because a variable can be in one and not the others.


# 1. systemd user manager
systemctl --user show-environment | grep QT_ENABLE_HIGHDPI_SCALING

# 2. D-Bus activation environment, read through a service it started
tr '\0' '\n' < /proc/$(pgrep -f /usr/lib/xdg-desktop-portal | head -1)/environ \
  | grep QT_ENABLE_HIGHDPI_SCALING

# 3. Hyprland's own process environment
tr '\0' '\n' < /proc/$(pgrep -x Hyprland | head -1)/environ \
  | grep QT_ENABLE_HIGHDPI_SCALING

A value present in 3 but missing from 1 and 2 means you set it with hl.env and have only reloaded, not logged out. A value missing from all three after a re-login means the file you edited is not being read, most often ~/.config/hypr/envs.lua, which nothing loads.

Sources

env-vars-in-hyprland-config-ignored-uwsm