Wayland Support and Configuration
GoldenDict-ng supports running both natively on Wayland and via XWayland (X11).
Since version 25.12.0, the application defaults to native Wayland on Wayland sessions to provide the best HiDPI and fractional scaling experience. However, due to Wayland's security design, certain features like global hotkeys and screen-grabbing popups may require switching back to X11 mode.
Mode Selection Hardware
The display mode is determined by environment variables at startup. You can specify your preference using the following flags:
| Mode | Environment Variable | Best For |
|---|---|---|
| Native Wayland (Default) | (None) or GOLDENDICT_FORCE_WAYLAND=1 |
HiDPI screens, smooth scaling, security. |
| XWayland (X11) | GOLDENDICT_FORCE_XCB=1 |
Global hotkeys, advanced ScanPopup (ScanFlag). |
How to Switch
1. Native Wayland (Default)
By default, the app will try to run as a native Wayland client. If you want to force it explicitly:
env GOLDENDICT_FORCE_WAYLAND=1 goldendict
2. XWayland / X11 Mode (Recommended for Hotkeys)
If you need global hotkeys (Ctrl+C+C etc.) or the "Scan Flag" feature to work across windows, run the app in X11 mode:
env GOLDENDICT_FORCE_XCB=1 goldendict
Flatpak Configuration
If you are using the Flatpak version, you can use Flatseal or the command line to set these variables:
# Force X11 mode for Flatpak
flatpak override --env=GOLDENDICT_FORCE_XCB=1 io.github.xiaoyifang.goldendict_ng
Technical Comparison
| Feature | Native Wayland | XWayland (X11) |
|---|---|---|
| HiDPI / Sharp Text | ⭐ Excellent | ⚠️ May be blurry |
| Global Hotkeys | ❌ Not Supported | ✅ Fully Supported |
| Scan Flag (Small Flag) | ❌ Disabled | ✅ Enabled |
| Window Positioning | ⚠️ Limited by compositor | ✅ Precise |
| Input Method (IME) | ✅ Supported (Qt 6) | ✅ Supported |
Global Hotkeys on Wayland
Native Wayland does not allow applications to listen to keyboard events globally. If you rely on Ctrl+C+C to trigger lookups from other apps, you must use X11 mode (GOLDENDICT_FORCE_XCB=1).
Workaround for Wayland Hotkeys
Users on KDE or GNOME can manually bind a custom system shortcut to a command that sends a word to GoldenDict, for example: goldendict "selection".
Note that the command argument is a literal word — goldendict "selection" only looks up the word selection itself. To look up the currently selected text (like ScanPopup on X11), read the mouse primary selection with wl-paste and pass it to GoldenDict in scan popup mode:
sh -c 'goldendict -s "$(wl-paste -p -n)"'
This requires wl-clipboard to be installed (sudo apt install wl-clipboard on Ubuntu/Debian). -p reads the primary selection (text highlighted with the mouse) and -n trims the trailing newline. Then bind this command to a shortcut in your desktop's shortcut settings (e.g. GNOME: Settings → Keyboard → View and Customise Shortcuts → Custom Shortcuts).
wl-paste is Wayland-only. This workaround is only needed in native Wayland mode; if you run GoldenDict in X11 mode (GOLDENDICT_FORCE_XCB=1), global hotkeys and ScanPopup already work and no shortcut is required.