XWayland: A Survival Guide

Most Linux desktops have moved to Wayland as the default display server, but the X11 ecosystem is vast. Thousands of applications still speak only the X11 protocol — legacy toolkits, older games, CAD tools, remote desktop clients. XWayland is the compatibility bridge: a full X server running as a Wayland client, intercepting X11 requests and compositing the results into your Wayland session. Understanding it saves hours of debugging when apps blur, refuse to launch, grab the keyboard incorrectly, or just silently die.

How XWayland Actually Works

XWayland (Xwayland binary, part of the xwayland package) starts on demand — usually when the first X11 client connects. Your compositor (GNOME Shell, KWin, Sway, etc.) creates a Wayland surface and hands XWayland control of it. From the X11 application's perspective it is talking to a perfectly normal X server. From the compositor's perspective XWayland is just another Wayland window.

Key implications:

• There is no shared memory space between Wayland and XWayland; clipboard and drag-and-drop need explicit bridging (handled by xdg-desktop-portal and the compositor).
• HiDPI scaling is coarse: the X11 model scales to integer multiples. Fractional scaling on Wayland does not carry over cleanly — you will see blurry X11 windows at 125 % or 150 %.
• Global keyboard shortcuts and raw pointer grabs work differently, which is why some screen-capture or hotkey tools behave oddly.
• Security isolation is real: X11 clients cannot snoop on Wayland windows (no more xdotool-style keyloggers across apps).

Installing and Verifying XWayland

Install the package if missing

Most desktop installs include XWayland already. If it is absent:

# Debian / Ubuntu
sudo apt install xwayland

# Fedora
sudo dnf install xorg-x11-server-Xwayland

# Arch
sudo pacman -S xorg-xwayland

Check whether an app is running under XWayland

Use xprop or xlsclients to list X11 clients currently connected to XWayland. If either returns output, XWayland is active.

xlsclients -display :0

For a specific window, click it and run:

xprop -display :0 | grep -i "class\|name"

On GNOME you can also install the Wayland or X11 extension, or run:

gdbus call --session \
  --dest org.gnome.Shell \
  --object-path /org/gnome/Shell \
  --method org.gnome.Shell.Eval \
  "global.display.get_focus_window().get_client_type()"

A return value of 1 means X11 (XWayland); 0 means native Wayland.

Common Misbehaviours and Fixes

Blurry windows at fractional scale

The X11 protocol has no concept of fractional DPI. XWayland renders at the nearest integer scale and the compositor stretches the result, causing blur. Two approaches fix this:

Option 1 — Force integer scaling for XWayland (Mutter/GNOME 43+):

gsettings set org.gnome.mutter experimental-features "['scale-monitor-framebuffer']"

This enables per-monitor fractional scaling properly. XWayland windows are rendered at 2× and downscaled sharply instead of upscaled blurrily.

Option 2 — Set GDK_SCALE or QT_SCALE_FACTOR per application:

GDK_SCALE=2 GDK_DPI_SCALE=0.5 myapp &

This tells the toolkit to render at 2× internally and then halve font sizes so everything looks correct at 200 % monitor scale. Adjust the multiplier to match your actual scale setting.

App refuses to start on Wayland, demands DISPLAY

Some apps hard-code checks for DISPLAY. XWayland sets DISPLAY=:0 (or :1) automatically once it starts, but the variable might not be exported to a specific shell session. Export it explicitly:

export DISPLAY=:0
myapp

If the variable is consistently missing, confirm XWayland started:

ps aux | grep -i xwayland

Forcing a GTK4 or Qt6 app to use Wayland natively (avoid XWayland)

Some apps default to X11 even though they ship a Wayland backend. Override it:

# GTK apps (GTK3/4)
export GDK_BACKEND=wayland

# Qt apps
export QT_QPA_PLATFORM=wayland

# Electron apps (Chromium-based)
myelectronapp --enable-features=UseOzonePlatform --ozone-platform=wayland

Persist these in ~/.config/environment.d/wayland.conf (parsed by systemd's user environment, picked up by all graphical sessions):

cat > ~/.config/environment.d/wayland.conf <<'EOF'
GDK_BACKEND=wayland
QT_QPA_PLATFORM=wayland;xcb
MOZ_ENABLE_WAYLAND=1
EOF

The wayland;xcb fallback syntax tells Qt to try Wayland first and fall back to X11 if unavailable — useful on machines that might boot into a pure X session.

Screen sharing and remote desktop broken

X11 screengrab tools (scrot, xwd, OBS with X11 capture) cannot see Wayland windows — they only capture XWayland's own virtual framebuffer. Use PipeWire-based capture instead. Confirm PipeWire is running:

systemctl --user status pipewire pipewire-pulse

In OBS, select Screen Capture (PipeWire) as the source. For browser-based screen sharing, ensure xdg-desktop-portal and the correct backend are installed:

# GNOME
sudo apt install xdg-desktop-portal-gnome   # Debian/Ubuntu
sudo dnf install xdg-desktop-portal-gnome   # Fedora

# KDE Plasma
sudo apt install xdg-desktop-portal-kde

# wlroots compositors (Sway, Hyprland, etc.)
sudo apt install xdg-desktop-portal-wlr

Input issues: hotkeys, clipboard, cursor shape

Global hotkey daemons that rely on XGrabKey (e.g. older versions of sxhkd, xbindkeys) will only intercept keys sent to XWayland clients, not the whole desktop. Switch to your compositor's native keybinding system or use a Wayland-native hotkey daemon.

Clipboard sync between X11 and Wayland clients is handled automatically by the compositor in most cases, but if it breaks, install and run xclip/wl-clipboard together, or ensure wl-paste is wired up:

wl-paste --watch xclip -selection clipboard &

Environment Variable Reference

Variable	Purpose	Common Values
DISPLAY	X11 display socket	:0, :1
WAYLAND_DISPLAY	Wayland socket	wayland-0, wayland-1
GDK_BACKEND	GTK backend selection	wayland, x11, wayland,x11
QT_QPA_PLATFORM	Qt platform plugin	wayland, xcb, wayland;xcb
MOZ_ENABLE_WAYLAND	Firefox native Wayland	1
GDK_SCALE	Integer scale factor for GTK apps	2
GDK_DPI_SCALE	Font DPI correction	0.5
ELECTRON_OZONE_PLATFORM_HINT	Electron Wayland hint (newer)	auto

When XWayland Is Not Enough: Alternatives

Some applications genuinely cannot work through XWayland — typically those that require direct GPU access via DRI in legacy mode, or tools that manipulate the X display server itself (display managers, compositors, Xephyr-based sandboxes).

• Run a nested X session with Xephyr: useful for testing or running an isolated X environment inside Wayland. Xephyr :1 -screen 1280x720 & then DISPLAY=:1 openbox &.
• A separate X.org seat: for hardware that truly needs a full X server (e.g. some NVIDIA workflows on older drivers), a second login seat running X.org alongside the Wayland session is viable using loginctl multiseat or a second TTY.
• Wine and games: Valve's Proton now ships with its own XWayland integration, and many native Linux games run better by explicitly setting SDL_VIDEODRIVER=wayland. Check the ProtonDB page for specific overrides.

Troubleshooting Checklist

• App crashes immediately → check journalctl --user -xe for BadWindow or GLX errors; the app may need LIBGL_ALWAYS_SOFTWARE=1 as a temporary diagnostic.
• XWayland not starting → ensure the package is installed and your compositor supports it; on Sway check sway -d 2>&1 | grep -i xwayland.
• Cursor invisible or wrong size → set XCURSOR_SIZE=24 and XCURSOR_THEME=Adwaita (or your theme) in your environment file.
• NVIDIA GPU → driver versions below 495 have partial XWayland support; 525+ with --explicit-sync patches (merged in Xwayland 24.1) are required for tear-free XWayland on NVIDIA. Check with nvidia-smi and compare to release notes.
• App sees wrong screen resolution → XWayland reads RANDR info from the compositor; if it reports wrong dimensions, the compositor's XWayland RANDR emulation may need a compositor update.