XWayland apps are blurry or pixelated on a scaled display
Re-checked on this workstation (omarchy 4.0.2-1, omarchy-settings 4.0.2-1, hyprland 0.56.2-1, kernel 7.1.9-arch1-2, NVIDIA) against the live system, the current Hyprland wiki markdown and Hyprland's source at tag v0.56.2. The mechanism and both Omarchy claims hold. The verify block is wrong in two ways and the toolkit advice is incomplete.
What held, and where. xwayland:force_zero_scaling is still the option name on 0.56.2 and reads bool: true, set: true here, and xwayland:use_nearest_neighbor reads bool: true, set: false, so the record's "default true" is confirmed live rather than only from the wiki. /usr/share/omarchy/default/hypr/envs.lua on this machine does set force_zero_scaling = true in an hl.config() block and does set XCURSOR_SIZE and HYPRCURSOR_SIZE to 24. /usr/share/omarchy/config/hypr/monitors.lua does carry local omarchy_gdk_scale and hl.env("GDK_SCALE", tostring(omarchy_gdk_scale)). The current wiki page content/configuring/extra/xwayland.md still recommends exactly force_zero_scaling plus GDK_SCALE and XCURSOR_SIZE with the monitor at highres, and still carries the warning against XWayland HiDPI patches, so the record's danger is right. The Arch HiDPI page confirms the Xft.dpi versus GDK_SCALE conflict with Firefox named as the usual casualty, and confirms --force-device-scale-factor for Electron and integer multiples of 96 for Xft.dpi.
Placement is right and this matters, because on Omarchy 4 most session environment comes from uwsm. hl.env() is nevertheless the correct place, not ~/.profile and not ~/.config/uwsm/env.d/, and that is confirmed on this machine rather than reasoned: ~/.config/hypr/monitors.lua here sets local omarchy_gdk_scale = 1 and systemctl --user show-environment reports GDK_SCALE=1, alongside XCURSOR_SIZE=24 from envs.lua. ~/.config/uwsm/ does not exist on this install at all. The record's claim that an env change needs a reload plus a relaunch is also correct: hlEnv in src/config/lua/bindings/LuaBindingsConfigRules.cpp at v0.56.2 calls setenv unconditionally and only short-circuits when the value is unchanged, so a reload does re-apply it.
What was wrong. The verify said hyprctl getoption xwayland.force_zero_scaling "returns 1". Run here it prints bool: true and set: true on two lines, never 1, so a reader following it literally concludes the option is unset. It also said hyprctl clients | grep -A2 xwayland shows xwayland: 1 for the app. Run here that prints xwayland: 0, pinned: 0, pinFullscreened: 0 and no class or title, because xwayland: N is itself the matched line, so it can never tell you which window the flag belongs to. Both replaced with checks that were run on this machine. The fix said GDK_SCALE is set "at the bottom" of monitors.lua, which is wrong on 4.0.2-1: in the shipped template the two locals and the hl.env line sit at the top above the catch-all rule, and the bottom of the file holds commented examples. The Qt advice set only QT_AUTO_SCREEN_SCALE_FACTOR, which the Arch HiDPI page records as replaced by QT_ENABLE_HIGHDPI_SCALING in Qt 5.14, and recommends setting both. Added a GDK_SCALE mismatch paragraph, because this workstation carries a first-hand instance of it in a comment in ~/.config/hypr/monitors.lua: GDK_SCALE=2 on a scale-1 27 inch 1440p panel made Steam draw zoomed with its titlebar drag region offset so its windows could not be moved. Finally the last block was fenced as bash while its first two lines were Lua. The previous auditor saw this and called it cosmetic. In a corpus whose whole claim is copy-pasteable fixes it is a defect, so the Lua line is now in its own Lua fence.
Not exercised. Nothing was written and no scale, mode or config was changed, because this is the operator's daily workstation driving a real panel and libvirt VMs. force_zero_scaling was read, never toggled. No app was relaunched to observe sharpness, so the visual outcome is from the wiki, not from a test here. _JAVA_OPTIONS and the Electron flag file were not tried. The XWayland client filter was validated against the real hyprctl clients output on this machine, but every window open at the time reported xwayland: 0, so the select(.xwayland) branch matched nothing and was checked by reading the field rather than by seeing it fire.
Swapped the two basecamp/omarchy blob URLs for omacom/omarchy, the current name. The old ones still redirect, but both files were re-fetched against omacom/omarchy@quattro for this audit.
Merged on 2026-09-13: xwayland-apps-blurry-hidpi was retired into this record and its page now 404s. Its 2026-09-13 re-audit found it near-identical to this one, same symptom, mechanism, primary fix, danger and three shared sources, and found its Omarchy fix telling the reader to write hl.env() lines into ~/.config/hypr/envs.lua, which nothing loads. Three things it held that this record did not are now above: the make-it-native-Wayland branch with the five variables Omarchy ships, the SDL_VIDEODRIVER gap, and the note that hypr/envs.lua is never required. Its full text is in the git history and in raw/o3-wayland-audio-audit.json.
Setting Xft.dpi at the same time as a toolkit scale such as GDK_SCALE makes interface elements much larger than intended in some programs (Firefox is the usual casualty). Pick one mechanism per toolkit. Do not install the old XWayland HiDPI patches. Upstream states they are no longer supported.
Symptom
On a HiDPI or fractionally scaled monitor, native Wayland apps look sharp but Steam, Zoom, older Electron builds, JetBrains IDEs, GIMP and Wine games are soft, fuzzy or visibly pixelated. The Hyprland FAQ answer people find is "This just means they are running through XWayland, which physically cannot scale by fractional amounts", which explains it but doesn't fix it. Turning scaling off makes them sharp and everything tiny.
Cause
Xorg has no per-output scale, so XWayland surfaces are rendered at 1x and then bitmap-scaled by the compositor to the monitor's scale factor. Any non-integer factor means resampling, hence the blur. xwayland:use_nearest_neighbor (default true) swaps blur for pixelation but does not add detail. The documented remedy is to stop the compositor scaling XWayland at all (xwayland:force_zero_scaling) and instead let each toolkit draw its own UI larger, but that only works if the toolkit env vars are actually set, and hl.env() only reaches processes Hyprland itself spawns after that line runs.
Fix
First confirm the app really is on XWayland:
hyprctl -j clients | jq -r '.[] | select(.xwayland) | "\(.class)\t\(.title)"'
xlsclients -l also works but is not installed by default on Omarchy 4 or on Arch, and needs xorg-xlsclients.
**Try making the app native Wayland first**, because that removes the problem rather than working around it. On Omarchy 4 this is already done for you, in /usr/share/omarchy/default/hypr/envs.lua:
hl.env("GDK_BACKEND", "wayland,x11,*")
hl.env("QT_QPA_PLATFORM", "wayland;xcb")
hl.env("MOZ_ENABLE_WAYLAND", "1")
hl.env("ELECTRON_OZONE_PLATFORM_HINT", "wayland")
hl.env("OZONE_PLATFORM", "wayland")
The only one of the usual set Omarchy does not ship is SDL_VIDEODRIVER. On plain Arch add all of the above plus hl.env("SDL_VIDEODRIVER", "wayland"). An app still on XWayland with those set either has no Wayland backend at all, which covers Steam, Wine and most Java Swing, or was started from a shell that predates the setting. For those, carry on below.
**Where hl.env() lines go on Omarchy 4.** There is no ~/.config/hypr/envs.lua and creating one does nothing: the stock ~/.config/hypr/hyprland.lua loads Omarchy's defaults and then requires exactly five user files, hypr.monitors, hypr.input, hypr.bindings, hypr.looknfeel and hypr.autostart. Put your lines in one of those, or add a require("hypr.envs") line to hyprland.lua yourself. User files load after Omarchy's defaults, so a value set there wins.
Force XWayland to render 1:1 and hand the scaling job to the toolkits. In ~/.config/hypr/hyprland.lua (plain Hyprland):
-- Monitor keeps its real resolution and fractional scale
hl.monitor({ output = "", mode = "highres", position = "auto", scale = 1.5 })
-- Stop the compositor from upscaling XWayland surfaces
hl.config({
xwayland = {
force_zero_scaling = true,
},
})
-- Now each toolkit scales itself. GTK only honours whole numbers, so use the
-- nearest integer to your monitor scale.
hl.env("GDK_SCALE", "2")
hl.env("XCURSOR_SIZE", "32")
-- Qt. QT_AUTO_SCREEN_SCALE_FACTOR was replaced by QT_ENABLE_HIGHDPI_SCALING in
-- Qt 5.14 and everything current on Arch is Qt 6, so set both.
hl.env("QT_AUTO_SCREEN_SCALE_FACTOR", "1")
hl.env("QT_ENABLE_HIGHDPI_SCALING", "1")
hl.env("QT_QPA_PLATFORM", "wayland;xcb")
**Omarchy 4 already does the first half for you.** force_zero_scaling = true is set in the hl.config() block at the end of /usr/share/omarchy/default/hypr/envs.lua, and XCURSOR_SIZE and HYPRCURSOR_SIZE are set to 24 in the same file. GDK_SCALE is set near the **top** of ~/.config/hypr/monitors.lua, above the catch-all monitor rule, from a local variable. Edit that file, not a new one:
-- ~/.config/hypr/monitors.lua
local omarchy_gdk_scale = 2
local omarchy_monitor_scale = "auto"
hl.env("GDK_SCALE", tostring(omarchy_gdk_scale))
hl.monitor({ output = "", mode = "preferred", position = "auto", scale = omarchy_monitor_scale })
or let Omarchy write both numbers consistently:
omarchy-hyprland-monitor-scaling 1.6
**Keep the two numbers in step.** GDK_SCALE must be the nearest integer to the monitor scale. Setting GDK_SCALE=2 on a monitor running at scale 1 makes every GTK and XWayland client draw at double size, and on Steam, which is XWayland plus CEF, it also offsets the titlebar drag region so the window cannot be moved. omarchy-hyprland-monitor-scaling writes both numbers together for exactly this reason, but only while monitors.lua still has Omarchy's generic shape.
Toolkits GDK_SCALE does not cover. Lua lines go in your Hyprland config:
-- Java / JetBrains
hl.env("_JAVA_OPTIONS", "-Dsun.java2d.uiScale=2")
The rest are per-app files, not environment variables:
# Electron/Chromium apps still on XWayland: a flag file, e.g. ~/.config/code-flags.conf
echo '--force-device-scale-factor=2' >> ~/.config/code-flags.conf
# Legacy X11 apps that read Xft.dpi (integer multiples of 96)
printf 'Xft.dpi: 192\n' >> ~/.Xresources
xrdb -merge ~/.Xresources
Env changes only reach apps started **after** the config is re-read. Hyprland re-runs every hl.env() line on reload, so hyprctl reload and then relaunch the app from a Hyprland keybind or the Omarchy menu is enough. Two things it is not enough for: a terminal that was already open keeps the old value and passes it to anything you start from it, and the systemd user environment is only guaranteed to match after a full session restart (log out and back in). Do not judge the fix by a window that was already open.
Verify
Relaunch the app, then confirm the option and the client:
hyprctl getoption xwayland:force_zero_scaling
# bool: true
# set: true
hyprctl -j clients | jq -r '.[] | select(.xwayland) | "\(.class)\t\(.title)"'
getoption prints bool: true, not 1. The dotted form xwayland.force_zero_scaling works too. The jq filter is the reliable way to find XWayland clients, because hyprctl clients | grep xwayland matches the xwayland: 0 flag line itself and never the window it belongs to. Text in the relaunched app should now be crisp rather than soft or blocky, and it should be the same physical size as a native Wayland window.
Sources
- https://wiki.hypr.land/Configuring/Advanced-and-Cool/XWayland/
- https://wiki.hypr.land/Configuring/Basics/Variables/
- https://wiki.hypr.land/FAQ/
- https://wiki.hypr.land/Configuring/Advanced-and-Cool/Environment-variables/
- https://wiki.archlinux.org/title/HiDPI
- https://wiki.hypr.land/configuring/extra/xwayland/
- https://wiki.hypr.land/configuring/core/environment-variables/
- https://wiki.hypr.land/configuring/core/monitors/
- 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/config/hypr/monitors.lua
- https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-hyprland-monitor-scaling