linux-wayland

name	linux-wayland
description	Use when implementing or troubleshooting Linux Wayland compatibility in Electron apps. Covers Ozone platform detection, GPU flags, and related environment setup.

Linux Wayland Compatibility

Overview

Electron on Linux defaults to X11. On Wayland compositors (GNOME 40+, KDE Plasma 5.21+, Sway), this forces XWayland fallback, which can cause rendering issues (black/white screens, lag, blurry text). The fix enables Electron's native Ozone/Wayland backend.

Detection

// src/main/env.ts
export const isLinux = process.platform === 'linux'

export const isWayland =
  isLinux &&
  (process.env.XDG_SESSION_TYPE === 'wayland' ||
    !!process.env.WAYLAND_DISPLAY)

XDG_SESSION_TYPE is set by systemd/logind. WAYLAND_DISPLAY is set by the compositor at launch. Either being present indicates a Wayland session.

GPU Flags

// src/main/index.ts — before app.whenReady()
if (isLinux && isWayland) {
  app.commandLine.appendSwitch('in-process-gpu')
  app.commandLine.appendSwitch('enable-features', 'UseOzonePlatform')
}

Why each flag

Flag	Purpose
enable-features: UseOzonePlatform	Tells Chromium to use the Ozone/Wayland backend instead of X11
in-process-gpu	Runs GPU process in the browser process. On Wayland, the GPU sandbox can't access the Wayland socket (/run/user/*/wayland-*), causing GPU process crashes. In-process avoids this.

Environment Variable (Build-time)

ELECTRON_OZONE_PLATFORM_HINT must be set before the Electron process starts. It cannot be set via app.commandLine — it's read by Chromium before JS runs.

In development:

ELECTRON_OZONE_PLATFORM_HINT=wayland pnpm dev

In production (via electron-builder wrapper):

ELECTRON_OZONE_PLATFORM_HINT=wayland ./moti

Common Issues

White/Black window on Wayland

Cause: Electron falling back to XWayland, or GPU process crash. Check chrome://gpu in DevTools for errors.

Fix: Ensure both in-process-gpu and UseOzonePlatform flags are set. Confirm ELECTRON_OZONE_PLATFORM_HINT=wayland is set before launch.

GPU process crashes on Wayland

Cause: GPU sandbox can't access Wayland socket. Error in logs: Failed to connect to Wayland display.

Fix: --in-process-gpu avoids the sandbox issue. On Electron 28+, also try --disable-gpu-sandbox as an alternative.

Native dialogs / file picker not working

Cause: Electron's native file dialog uses GTK/X11 on some setups.

Fix: Ensure libgtk-3-0 and xdg-desktop-portal-gtk are installed. On pure Wayland (Sway), install xdg-desktop-portal-wlr.

Text rendering is blurry

Cause: XWayland scaling. --enable-features=UseOzonePlatform with ELECTRON_OZONE_PLATFORM_HINT=wayland should resolve.

Verification

# Check if running under Wayland
echo $XDG_SESSION_TYPE  # should output "wayland"

# Check Electron's GPU backend (in DevTools console or chrome://gpu)
# Look for "Ozone platform: wayland" in the GPU info page

Supported Electron Versions

Ozone/Wayland support stabilized in Electron 12+ with significant improvements in Electron 28+. The UseOzonePlatform flag is available from Chromium 92+ (Electron 14+).

References

• Electron Wayland docs
• src/main/env.ts — isWayland detection
• src/main/index.ts — GPU flag application