Run X11 Apps on Wayland: Step-by-Step

Wayland is the modern display server on many Linux desktops, but some older or specialized applications still require X11. This guide shows you how to run those X11-only apps on a Wayland session, either through the built-in XWayland compatibility layer or by forcing the app to use X11 explicitly. You’ll learn the exact commands and settings needed, plus how to fix common issues.

What You’ll Need

• A Linux distribution running a Wayland session (GNOME, KDE Plasma, Sway, etc.)
• An X11-only application installed (e.g., some older games, proprietary tools, or apps that don’t support Wayland)
• Basic familiarity with the terminal

Step-by-Step

1. Check your session type. Open a terminal and run echo $XDG_SESSION_TYPE. If it prints wayland, you’re in a Wayland session. If it prints x11, you’re already using X11 and don’t need this guide.
2. Try launching the app normally. Many X11 apps run automatically through XWayland, a compatibility layer that Wayland compositors include. Just launch the app from your application menu or terminal (e.g., myapp). If it opens, you’re done—it’s already using XWayland.
3. If the app doesn’t start, force X11 via environment variable. Some apps check for Wayland support and may try to use it, but fail. Set GDK_BACKEND=x11 for GTK apps or QT_QPA_PLATFORM=xcb for Qt apps. For example: GDK_BACKEND=x11 myapp or QT_QPA_PLATFORM=xcb myapp.
4. For Electron-based apps, add the --disable-gpu flag if they crash, or set ELECTRON_OZONE_PLATFORM_HINT=x11 to force X11.
5. If the app still won’t run, check if XWayland is installed. On most distros, it’s installed by default, but you can verify with which Xwayland. If missing, install it via your package manager (e.g., sudo apt install xwayland on Debian/Ubuntu).
6. Launch the app with explicit X11 display. If the app uses a specific display, run DISPLAY=:0 myapp (or :1 if that’s your XWayland display). Usually XWayland uses :0 by default.
7. For full-screen games or apps with graphics issues, try running with LIBGL_ALWAYS_SOFTWARE=1 to force software rendering, which can fix black screens or crashes.
8. If the app needs root or special permissions, use sudo carefully, but note that running GUI apps as root is generally discouraged. Instead, try to fix permission issues (e.g., for USB devices) via udev rules.
9. If you need to run multiple X11 apps with different settings, create a small shell script for each app with the necessary environment variables.

Common Mistakes

• Assuming all apps run under Wayland natively—most older apps don’t, and that’s fine.
• Forgetting to set the environment variable before launching the app; it must be in the same command or exported in the shell.
• Setting GDK_BACKEND=x11 for a Qt app—that won’t work; use the correct variable for the toolkit.
• Using DISPLAY=:0 when your XWayland display is different. Check with echo $DISPLAY in a terminal where X11 apps work.
• Killing XWayland to “fixâ€� an issue—that will break all X11 apps.

Tips

• Use env | grep -i wayland to see Wayland-related variables; some apps need WAYLAND_DISPLAY unset to force X11.
• For persistent settings, add the environment variables to your shell profile (e.g., ~/.bashrc) or to the app’s desktop file in ~/.local/share/applications.
• If an app has scaling issues, try setting GDK_SCALE=2 (for HiDPI) or QT_SCALE_FACTOR=2.
• For games, consider using gamescope to run them in a nested Wayland session, which can improve compatibility.
• Keep your system updated; XWayland improvements are frequent.

Troubleshooting

• App opens but shows a black window. Try software rendering: LIBGL_ALWAYS_SOFTWARE=1 myapp. If that works, your GPU drivers may need updating.
• App crashes immediately. Run it from the terminal to see error messages. Common fixes: install missing 32-bit libraries (if the app is 32-bit), or set GDK_BACKEND=x11 if it’s a GTK app.
• App runs but has no sound. Check if PulseAudio or PipeWire is running. X11 apps may need SDL_AUDIODRIVER=pulseaudio or ALSA config.
• Keyboard or mouse input doesn’t work. This is rare, but try setting QT_X11_NO_MITSHM=1 for Qt apps, or check your compositor’s input settings.
• App is very slow. XWayland can be slower than native X11. Try disabling compositing in the app, or use LIBGL_ALWAYS_INDIRECT=1 for OpenGL apps (though this may break some).
• Cannot drag windows between monitors. This is a known XWayland limitation; some compositors handle it better than others. Try moving windows with keyboard shortcuts (e.g., Super+Shift+Arrow in GNOME).

Frequently Asked Questions

Q: Do I need to install XWayland separately?

A: Usually not—most Wayland compositors include it. But if you get an error like “cannot open displayâ€�, install the xwayland package from your distro’s repos.

Q: Why does my app still run under Wayland even when I set GDK_BACKEND=x11?

A: Some apps override that variable internally. Try unsetting WAYLAND_DISPLAY as well: env -u WAYLAND_DISPLAY GDK_BACKEND=x11 myapp.

Q: Can I run X11 apps on a pure Wayland session without XWayland?

A: No—XWayland is required for X11 apps. There’s no other way to run them on Wayland.

Q: Will X11 apps run faster under XWayland than native X11?

A: Usually slightly slower due to the extra translation layer, but for most apps the difference is negligible. Games may see a performance hit.

Q: How do I know if an app is using XWayland?

A: Run xlsclients (from x11-utils) in a terminal; it lists X11 clients connected to the X server, which includes XWayland.

Q: Can I force a Wayland-native app to run under X11?

A: Yes, but it’s not recommended. You can set GDK_BACKEND=x11 for GTK apps or QT_QPA_PLATFORM=xcb for Qt apps, but Wayland-native features like fractional scaling may not work.

Related

• Why Windows 11 Setup Wants a Microsoft Account
• Change WhatsApp Call & Message Sounds on Samsung Galaxy
• How to Let Someone Else Use Your Twitter Account