Linux Troubleshooting Guide
Linux has two display server protocols — Wayland and X11 — and each requires different tools for simulating keyboard input. This guide will help you get everything working.
Most modern distributions (Fedora 40+, Ubuntu 24.04+, GNOME 46+) default to Wayland. Older setups or those using certain NVIDIA drivers may still run X11.
How do I know if I'm on Wayland or X11?
Check your display server
Open a terminal and run this command:
If the output is empty, you're likely on X11. Some display managers don't set this variable.
Wayland setup
For Fedora, Ubuntu, Arch, and other modern distros
Wayland needs ydotool — a display-server-independent input emulator that talks directly to the kernel. It requires a background daemon and permission to write to /dev/uinput.
Fedora / Fedora Atomic
Install ydotool
For standard Fedora:
On Fedora Atomic variants (Silverblue, Kinoite, Universal Blue), use rpm-ostree install ydotool && systemctl reboot instead.
Enable the daemon
Start ydotoold now and configure it to start on every boot:
Add your user to the input group
Grant your user permission to use the virtual input device:
You must log out and log back in (or reboot) for the group change to take effect.
Verify it works
Test that ydotool can simulate key presses:
Ubuntu / Debian
Install ydotool
Enable the daemon, add to input group, and verify
Same steps as Fedora above:
Arch Linux
Install ydotool
Enable the daemon, add to input group, and verify
Same steps as Fedora above:
X11 setup
For older or traditional distributionsX11 uses xdotool, which is simpler — no daemon needed, and it usually works out of the box.
Install xdotool
Pick the command for your distribution:
That's it
xdotool works immediately after installation. No daemon or group changes needed.
Text input on Wayland
If you use the Type Text action on Wayland, MIDI Mapper needs wtype to type characters.
wtype is only needed for typing text strings. Keyboard shortcut simulation uses ydotool.
Common issues
"ydotool: command not found"
ydotool is not installed. Follow the Wayland setup steps above for your distribution.
Keys fire but nothing happens
The ydotoold daemon is probably not running. Check its status and restart it:
"Permission denied" or "Failed to open /dev/uinput"
Your user is not in the input group. Add yourself and log out/in:
Remember to log out and back in after running this command.
Keyboard shortcuts aren't captured in the app
Your desktop compositor (GNOME, KDE, Cosmic) may intercept certain shortcuts before they reach the app. Check your system's keyboard shortcut settings and disable any that conflict, or type the key combination manually in MIDI Mapper's text field instead of using the capture button.
SELinux blocks ydotool (Fedora)
On Fedora, SELinux may block ydotool from accessing /dev/uinput. Check for denials:
If denials appear, create a local SELinux policy exception. This is an advanced step — refer to Fedora's SELinux documentation for details.
You're all set!
Your Linux system is configured for MIDI Mapper keyboard shortcuts and text input.