Quick Start — Switch to Wayland in 5 Minutes
Before touching any config files, check which display server you’re currently running:
echo $XDG_SESSION_TYPEIf it prints x11, you’re still on X11. If it says wayland, you’re already there — but stick around because the compatibility section below will save you some headaches.
On Ubuntu 22.04 and later, Wayland is available at the login screen. Log out, click your username, and look for the gear icon at the bottom-right. Select Ubuntu on Wayland instead of the default X11 session, then log in.
Ubuntu 24.04 ships with Wayland as the default, so you might already be running it without realizing it.
For Arch Linux with GNOME:
# GDM handles this automatically — just make sure it's enabled
sudo systemctl enable gdm
# At login, select GNOME (Wayland) from the session menuFor Arch with KDE Plasma 6 (current since early 2024), Wayland is already the default session — select Plasma (Wayland) at the SDDM login screen, no extra packages needed. On older Plasma 5 setups:
sudo pacman -S plasma-wayland-session
# Then select Plasma (Wayland) at the SDDM login screenThat’s the 5-minute version. Now let me tell you what actually breaks and how to deal with it.
Under the Hood — What X11 and Wayland Do Differently
X11 has been around since 1984. It was designed in an era when the assumption was that any application on the same desktop could read pixels from any other window. Flexible, yes — but that’s also why keyloggers and screen scrapers work so easily on X11. Wayland fixes this by isolating each window. Clients can only see their own content.
The tradeoff: older tools that relied on X11’s permissive model will flat-out stop working. Here’s what you’ll likely hit:
Screen Recording and Screenshots
Tools like scrot, import (ImageMagick), and older versions of OBS can’t capture other windows on Wayland. Switch to native alternatives:
# Install grim (screenshot) and slurp (region selector) on Wayland
# Ubuntu
sudo apt install grim slurp
# Arch
sudo pacman -S grim slurp
# Take a screenshot of a selected region
grim -g "$(slurp)" ~/screenshot.png
# Full screen
grim ~/fullscreen.pngOBS added Wayland support in version 27 (mid-2021) via PipeWire. Current distros ship version 30+, so you’re almost certainly covered — but verify PipeWire is actually running:
systemctl --user status pipewire pipewire-pulse
# Start if not running
systemctl --user start pipewire pipewire-pulse wireplumberApps That Still Need X11 — Enter XWayland
XWayland is a compatibility layer that runs an X server inside your Wayland session. Most Wayland compositors start it automatically when an X11 app launches. Legacy Electron apps, older Java GUIs, and Wine games typically just work through it. The caveats come with HiDPI scaling and input handling — those can get messy.
Check if an app is running under XWayland:
xlsclientsAny app listed there is going through XWayland, not native Wayland.
Remote Desktop and SSH X Forwarding
X11 forwarding (ssh -X) doesn’t work natively under Wayland sessions. Two options if you need GUI apps over SSH:
# Option 1: Keep an X11 session on the remote host and forward from there
ssh -X user@remote xterm
# Option 2: Use Waypipe for Wayland-native forwarding
# On Arch
sudo pacman -S waypipe
# Connect with Waypipe
waypipe ssh user@remote wayland-appAdvanced Usage — Environment Variables and Per-App Fixes
Some apps need a nudge to use Wayland natively instead of falling back to XWayland. A handful of environment variables handle most of these cases.
Force Wayland for Qt and GTK Apps
# Add to ~/.bash_profile or ~/.zshenv
export QT_QPA_PLATFORM=wayland
export GDK_BACKEND=wayland
export CLUTTER_BACKEND=wayland
export SDL_VIDEODRIVER=waylandBe careful with SDL_VIDEODRIVER=wayland — some games will crash with this set. I keep it commented out and only enable it for apps I know support it.
Firefox and Chromium Native Wayland
Both browsers support native Wayland but don’t always auto-detect it:
# Firefox — add to /etc/environment or your shell profile
MOZ_ENABLE_WAYLAND=1
# Or launch with the flag directly
MOZ_ENABLE_WAYLAND=1 firefox
# Note: Firefox 121+ (Dec 2023) detects Wayland automatically — this variable mainly helps older builds
# Chromium (Arch Linux) — flags file lives at the root of ~/.config, not inside the profile folder
echo "--ozone-platform=wayland" >> ~/.config/chromium-flags.conf
# Google Chrome
echo "--ozone-platform=wayland" >> ~/.config/google-chrome-flags.confAfter this, you’ll get proper HiDPI rendering and no blurry fonts on 4K displays.
Electron Apps (VS Code, Slack, Discord)
# VS Code — test with the flags inline first
code --enable-features=UseOzonePlatform --ozone-platform=wayland
# Make it permanent — write directly to the flags file (~/.config already exists)
echo "--enable-features=UseOzonePlatform --ozone-platform=wayland" >> ~/.config/code-flags.conf
# For other Electron apps, override the .desktop file
# Copy to user local directory first
cp /usr/share/applications/slack.desktop ~/.local/share/applications/
# Then edit the Exec line to add the Wayland flagsScreen Sharing in Video Calls (Zoom, Teams, Google Meet)
This was the most painful part of my migration. Screen sharing under Wayland requires PipeWire and the xdg-desktop-portal package:
# Ubuntu
sudo apt install xdg-desktop-portal xdg-desktop-portal-gnome pipewire-audio
# Arch
sudo pacman -S xdg-desktop-portal xdg-desktop-portal-gnome pipewire pipewire-pulse
# Verify portals are running
systemctl --user status xdg-desktop-portal xdg-desktop-portal-gnomeZoom added native Wayland support in version 5.12 (early 2022). Current builds handle it well. If screen sharing shows a black screen, check that PipeWire is active — not PulseAudio running standalone.
Practical Tips From Running Wayland Day-to-Day
Always Keep a Fallback X11 Session
Don’t remove X11 from your system. Ubuntu lets you switch back at the login screen anytime. GDM and SDDM on Arch both offer both session types. I keep X11 around for the occasional app that refuses to cooperate — mostly proprietary screen-sharing tools for corporate meetings.
Clipboard Behavior Is Different
X11 keeps clipboard content alive even after the source app closes. Wayland doesn’t — close the app that copied something, and that clipboard entry vanishes. A clipboard manager fixes this permanently:
# Ubuntu / Debian
sudo apt install wl-clipboard cliphist
# Arch
sudo pacman -S wl-clipboard cliphist
# Add to your Wayland session autostart (example for GNOME via .profile)
wl-paste --watch cliphist store &Check GPU and Compositor Acceleration
On my Ubuntu 22.04 workstation with 4GB RAM, switching to Wayland knocked around 180–220MB off my idle memory footprint compared to X11 with Compiz. The compositor — Mutter on GNOME, KWin on KDE — talks directly to the GPU, skipping the translation layer X11 needed in between.
Verify hardware acceleration is active:
# Check if GNOME Mutter is using hardware rendering
GSETTINGS_SCHEMA_DIR=/usr/share/glib-2.0/schemas gsettings get org.gnome.mutter experimental-features
# For more detail on GPU activity
GLXINFO=$(which glxinfo 2>/dev/null); [ -n "$GLXINFO" ] && glxinfo | grep "direct rendering"
# Wayland-specific: check DRM device
ls /dev/dri/Debugging App Issues
When an app behaves strangely on Wayland, launch it from terminal to see error output:
# Run with verbose Wayland debug output
WAYLAND_DEBUG=1 your-app 2>&1 | head -50
# Or check if forcing XWayland helps (useful for diagnosis)
GDK_BACKEND=x11 your-gtk-app
QT_QPA_PLATFORM=xcb your-qt-appIf the app works fine with GDK_BACKEND=x11 but not on native Wayland, you’ve found a compatibility issue specific to that app. Short-term fix: keep it on XWayland while upstream developers catch up.
Input Method Editors (CJK Languages)
If you type in Japanese, Chinese, or Korean, input method support on Wayland deserves attention. Fcitx5 handles Wayland much better than Fcitx4 or IBus in most setups:
# Install Fcitx5 with Wayland support
# Ubuntu
sudo apt install fcitx5 fcitx5-mozc fcitx5-gtk fcitx5-qt
# Arch
sudo pacman -S fcitx5 fcitx5-mozc fcitx5-gtk fcitx5-qt
# Add to ~/.profile or /etc/environment
GTK_IM_MODULE=fcitx
QT_IM_MODULE=fcitx
XMODIFIERS=@im=fcitxThe migration isn’t always smooth, and some tools will keep pulling you back to XWayland for a while. But native Wayland gives you better security isolation, smoother animation (no screen tearing by design), and better HiDPI support that keeps improving. Run both sessions in parallel during the transition — there’s no need to cut X11 off cold turkey.
