How to setup Onboard Virtual Keyboard for Debian 13 + KDE Plasma 6 + Wayland (uinput-based)

Preface: From Almost Giving Up to Finally Being Able to Type

Honestly, this article was written when I was very close to giving up on using an on-screen keyboard under KDE Plasma Wayland.

On Debian 13 with KDE Plasma 6 running on Wayland, the only officially supported virtual keyboard is Maliit.
In practice, however, it comes with a series of nearly deal-breaking problems:

• The keyboard only appears once
• After swiping it down, it can never be summoned again
• Requires restarting KWin or the entire desktop session
• Completely unsuitable for real tablet or 2-in-1 usage

After digging through GitHub issues and KDE Discuss threads, I honestly started to think:

“Maybe choosing KDE Wayland on a touch device is simply a dead end.”

That changed when I found a KDE Discuss thread from 2022:

Plasma 6 and Wayland no on-screen keyboard working - Help - KDE Discuss

In that thread, a user named @INVICTRA mentioned:

I managed to get Onboard working on wayland. Kubuntu 25.04

Edit the shortcut and add GDK_BACKEND=x11
Set input source to GTK
Set keystroke generator to uinput

The post was short and incomplete, but it revealed something important:

Onboard + X11 backend + uinput might be the real breakthrough.

With that clue, I started experimenting, filling in the missing pieces: kernel modules, permissions, udev rules, and Wayland constraints.
In the end, I successfully achieved a stable, repeatable, non-freezing virtual keyboard on:

Debian 13 + KDE Plasma 6 + Wayland

This article is the fully documented result of that process.

---

1. Why This Is Necessary (Background)

• As of late 2025, KDE Plasma Wayland officially supports only Maliit
• Maliit currently suffers from severe bugs on Plasma (cannot be re-opened after hiding)
• Wayland intentionally forbids synthetic input (fake keyboard/mouse events)
• Onboard can create a real input device via the Linux kernel uinput subsystem
• uinput devices are kernel-level input devices and are not blocked by Wayland

In short:

Wayland does not allow you to fake keystrokes,
but uinput lets you attach a real virtual keyboard.

Under Debian + KDE Plasma Wayland today,
this is practically the only solution that actually works.

---

2. System Requirements

• Debian GNU/Linux 13
• KDE Plasma 6
• Wayland session
• XWayland installed (usually installed by default)
• User has sudo privileges

---

3. Install Required Packages

sudo apt update
sudo apt install onboard xwayland

---

4. Enable the Kernel uinput Module

1. Check if uinput is loaded

lsmod | grep uinput

If there is no output, load it manually:

sudo modprobe uinput

2. Enable uinput at boot

echo uinput | sudo tee /etc/modules-load.d/uinput.conf

---

5. Configure uinput Permissions (Critical Step)

1. Create the group

sudo groupadd -f uinput

2. Add your user to the group (example: hln)

sudo usermod -aG uinput hln

Important: You must log out or reboot after this step.

---

3. Create a udev rule

sudo nano /etc/udev/rules.d/99-uinput.rules

Contents:

KERNEL=="uinput", MODE="0660", GROUP="uinput"

Reload rules:

sudo udevadm control --reload
sudo udevadm trigger

---

4. Verify After Reboot

ls -l /dev/uinput

Expected output:

crw-rw---- 1 root uinput /dev/uinput

Confirm group membership:

groups

You should see uinput.

---

6. Launch Onboard Using the X11 Backend (Very Important)

Under Wayland, Onboard must be forced to use the X11 backend:

GDK_BACKEND=x11 onboard

It is recommended to test this first in a terminal.

---

7. Required Onboard Settings

Open Onboard → Preferences → Keyboard → Advanced

Set the following:

• Input Options

  • Input event source: GTK

• Keystroke Generation

  • Key-stroke generator: uinput

If you previously tried uinput and it did not work,
you must re-test after completing the permission setup.

---

8. Verification

1. Open a text-input application (Kate / Firefox / Konsole)
2. Focus a text field
3. Click keys on Onboard

Successful behavior:

• Text appears in the application
• Keyboard can be shown and hidden repeatedly
• No need to restart KWin
• No freezing or dead state
• Completely avoids Maliit bugs

---

9. Create a Desktop Launcher (Recommended)

nano ~/.local/share/applications/onboard-x11.desktop

Contents:

[Desktop Entry]
Name=Onboard (Wayland Safe)
Exec=env GDK_BACKEND=x11 onboard
Type=Application
Icon=onboard
Categories=Utility;Accessibility;

You can now:

• Pin it to the KDE panel
• Place it on the desktop
• Use it as a one-click virtual keyboard launcher

---

10. Limitations and Notes

Known Limitations

• Does not work on the SDDM login screen
• Not Wayland-native (runs via XWayland)
• Elevated input permissions (recommended for personal devices only)

Advantages

• No swipe-down freeze issue
• Full Ctrl / Alt / Function key support
• Works with Fcitx5 (Chewing / Zhuyin)
• Compatible with Synergy / KVM
• Stable for long-term use

---

11. Reverting the Setup (Optional)

sudo rm /etc/udev/rules.d/99-uinput.rules
sudo gpasswd -d hln uinput
sudo reboot

---

12. Conclusion

On Debian 13 with KDE Plasma Wayland:

Onboard + uinput is currently the only virtual keyboard solution that truly works.

It is not an official or perfect solution,
but KDE is a volunteer-driven community, and expectations should remain realistic.

What matters most is that the problem is solved:
I can now use a keyboard-less tablet to type Taiwanese Mandarin with Zhuyin or English and actually get work done.