vboard

A virtual keyboard for GNU/Linux with Wayland support on KDE Plasma, plus GNOME support via Xwayland, and Ctrl, Alt, Tab and Super (Meta/Win) keys.

Wayland-compatible on KDE Plasma; also works on GNOME via Xwayland.

It supports many themes, as you can see below:

Overview

vboard is a lightweight, customizable virtual keyboard designed for Linux desktop systems. It runs as a Wayland-compatible on-screen keyboard on KDE Plasma, and also works on GNOME by falling back to Xwayland. It provides a full on-screen keyboard with modifier keys such as Ctrl, Alt, and Super (Meta/Win), which makes it especially useful for:

• Touchscreen devices without physical keyboards
• Systems with malfunctioning physical keyboards
• Accessibility needs
• Kiosk applications

The keyboard supports customizable colors, opacity settings, and can be easily modified to support different layouts.

Features

• Customizable appearance: Change background color and opacity
• Persistent settings: Configuration is saved between sessions
• Modifier key support: Provide Ctrl, Alt, Tab and Super (Meta/Win) keys
• Desktop compatibility: Native Wayland-friendly behavior on KDE Plasma, with GNOME support via Xwayland fallback
• Hold for repetitive clicks: Keep holding the mouse button to trigger repeated clicks
• Word suggestions: Offers completions from an installed Hunspell dictionary while you type with vboard
• Gesture typing: Swipe across letter keys and vboard will decode the path into a word
• Compact interface: Headerbar with minimal controls to save screen space
• Tray icon support: Keeps vboard running in the background and you can quickly reopen it when needed
• uinput input backend: Injects keys through Linux uinput

Implementation notes for gesture typing are documented in GESTURE_TYPING.md.

Installation

Ubuntu/Debian: .deb package

Download the latest .deb from the GitHub Releases page for a lightweight on-screen keyboard with modifier keys such as Ctrl, Alt, Shift, and Super, then install it with:

sudo apt install ./vboard_*.deb

DO NOT use dpkg. Please use apt. Otherwise, it will not work.

The package post-install step sets up uinput and installs the udev rule needed for desktop-session access to /dev/uinput.

Log out and back in, or reboot, after installation.

PPA for Ubuntu

You can also use the following PPA in Ubuntu. Run the following commands one by one:

sudo add-apt-repository ppa:apandada1/vboard
sudo apt update
sudo apt install vboard

Restart for changes to take effect.

Ubuntu/Debian: install from source

For the latest unreleased changes on Ubuntu and Debian-based systems, use the automated setup script:

git clone https://github.com/archisman-panigrahi/vboard.git
cd vboard
sudo bash setup-ubuntu-debian.sh

This script will handle all setup steps including dependency installation, uinput configuration, and system-wide installation. A system restart is recommended after installation.

Manual installation on other distros

For Debian/Ubuntu, Fedora, Arch, and other distributions, install the dependencies manually and then build with Meson.

1. Install dependencies

For Debian/Ubuntu-based distributions:

sudo apt install python3-gi python3-gi-cairo gir1.2-gtk-3.0 python3-uinput gir1.2-ayatanaappindicator3-0.1 meson ninja-build --no-install-recommends

Optional for word suggestions:

sudo apt install hunspell-en-us

For Fedora-based distributions:

sudo dnf install python3-gobject python3-cairo gtk3 python3-uinput python3-setuptools libappindicator-gtk3 meson ninja-build

Optional for word suggestions:

sudo dnf install hunspell-en-US

In Fedora KDE, you will also have to create a symlink for qdbus

sudo ln -sf /usr/bin/qdbus-qt6 /usr/local/bin/qdbus6

For Arch-based distributions:

sudo pacman -S python-gobject gtk3 python-uinput python-cairo libayatana-appindicator meson ninja

Optional for word suggestions:

sudo pacman -S hunspell-en_us

2. Clone the repository

git clone https://github.com/archisman-panigrahi/vboard.git
cd vboard

3. Prepare uinput (required)

Run once with sudo before Meson install:

sudo bash scripts/setup-uinput.sh

For system installs, this also installs a udev rule so your logged-in desktop user can access /dev/uinput. If permissions still do not apply, log out/log in or restart your computer.

4. Build and install with Meson

Global install:

meson setup builddir --prefix=/usr/local
meson compile -C builddir
sudo meson install -C builddir

User-only install:

meson setup builddir-user --prefix=$HOME/.local
meson compile -C builddir-user
meson install -C builddir-user

Restart for changes to take effect. On KDE/Plasma, install hooks automatically create the appropriate KWin window rule for vboard using its Wayland application ID instead of the window title.

5. Uninstall

meson compile -C builddir uninstall-local

For system installs:

sudo meson compile -C builddir uninstall-local

KDE Plasma: enable vboard as the default on-screen keyboard

After installation, open System Settings, search for Virtual Keyboard, and select Vboard.

Usage

When launched, vboard presents a compact keyboard with a minimal interface. The keyboard includes:

• Standard QWERTY layout keys
• Arrow keys
• Modifier keys (Shift, Ctrl, Alt, Super)
• Header-bar suggestions that appear while typing words through vboard when a system Hunspell dictionary is available
• Experimental swipe typing on alphabetic keys: drag across the intended letters and release to insert the best matching dictionary word

Interface Controls

• ☰ (menu) - Toggle visibility of other interface controls
• Options - Open in-app options for typing, startup, layout, about, bug reports, and quit actions
• + - Increase opacity
• - - Decrease opacity
• Background dropdown - Change the keyboard background color or pick an enhanced color theme
• Right-click a key - Send Shift + that key once
• Tray icon click - Hide or show vboard
• Tray icon right-click - Open tray controls when the tray backend supports a separate context menu

Configuration

vboard saves its settings to ~/.config/vboard/settings.conf. This configuration file stores:

• Background color
• Theme style
• Text prediction enabled/disabled state
• Gesture typing enabled/disabled state
• Start minimized enabled/disabled state
• Keyboard layout
• Opacity level
• Text color

You can manually edit this file or use the built-in interface controls to customize vboard.

Customizing Keyboard Layout

Keyboard layouts are JSON files. Packaged layouts are installed to:

/usr/share/vboard/vboard/layouts/

User layouts can be added or overridden in:

~/.config/vboard/layouts/

Each layout file defines an id, display label, rows, optional key labels, and optional shifted output. To customize a packaged layout, copy its JSON file into ~/.config/vboard/layouts/, edit it, and restart vboard.

Troubleshooting

Input does not work

If vboard opens but pressing keys does not type anything, the uinput backend usually could not open /dev/uinput.

1. Check whether uinput exists and inspect its permissions:

ls -l /dev/uinput

2. Run the setup helper again as root:

sudo bash scripts/setup-uinput.sh

3. Reload udev rules and retrigger the device:

sudo udevadm control --reload-rules
sudo udevadm trigger --subsystem-match=misc --sysname-match=uinput

4. Log out and back in, or reboot, so your desktop session picks up the updated device permissions.

5. If it still does not work, add your user to the input group and log out/in again:

sudo usermod -a -G input $USER

You can also start vboard from a terminal and look for errors such as Could not initialize uinput backend ([Errno 13]).

Error: no such device

Make sure uinput module is loaded:

sudo modprobe uinput

To auto-load at boot:

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

Error: Permission denied

Run uinput setup script:

sudo bash scripts/setup-uinput.sh

This installs the packaged udev rule at /etc/udev/rules.d/70-vboard-uinput.rules for system installs. If needed, reload udev, then log out/log in or reboot:

sudo udevadm control --reload-rules
sudo udevadm trigger --subsystem-match=misc --sysname-match=uinput

Contributing

Contributions are welcome.

Credits

Originally created by mdev588. The original project was archived, and it is now maintained by Archisman Panigrahi.

Original project: https://github.com/mdev588/vboard

Special thanks to honjow for the icon and patches.

Thanks to Yavuz Kagan Yadigar for the enhanced theme inspiration.

Thanks to onboard developers for the droid theme inspiration.

Thanks to the Hunspell project for the suggestion engine.

This project is licensed under GPLv3.

License

vboard is licensed under the GNU General Public License v3. See LICENSE for details.

Note

Currently only the QWERTY US layout is supported.