GamepadKey 🎮

Use an Xbox controller as a keyboard and mouse on Linux (Wayland).

GamepadKey lets you assign controller buttons to keyboard keys, left click, or right click. A thumbstick can move the pointer, and profiles let you keep different layouts for games and desktop applications. It works on both Wayland and X11.

GamepadKey is designed for Xbox controllers using xpadneo and currently supports one controller at a time.

Install

1. Install xpadneo

Check out their offcial repo or use your OS package manager.

2. Add my repo

Add my repository using these instructions

3. Install gamepadkey

sudo apt install gamepadkey

Getting started

1. Connect the Xbox controller and wait for the status at the top of the window to say Connected.
2. Select a controller button in the mapping list and choose the keyboard or mouse action it should perform.
3. To map quickly, select Press controller button… and press the desired controller button.
4. Choose a thumbstick under pointer settings if you want controller-driven mouse movement. You can adjust its deadzone, speed, acceleration, and axis direction.
5. Close the window when finished. GamepadKey continues running in the system tray.

Mappings take effect immediately and remain active until disabled or GamepadKey is quit. Closing the configuration window does not quit the application.

Profiles

Profiles are useful when the same controller should behave differently in different situations. You can create, rename, duplicate, and delete profiles from Manage profiles.

Choose a profile manually from the window at any time. A manual choice pauses automatic switching; select Resume automatic switching when you want application-based profile selection again. Applications without a matching profile use the default profile.

Profiles are stored in:

~/.config/gamepadkey/profiles.json

GamepadKey keeps a backup of the last valid configuration next to this file.

Desktop integration

The package includes helpers for detecting the focused application:

• On GNOME, enable GamepadKey Integration in the Extensions application.
• On KDE Plasma, enable GamepadKey Focus Reporter under KWin Scripts in System Settings.
• On X11, focused-application detection works without an additional helper.
• Other Wayland desktops can still use manual profile switching and a StatusNotifier-compatible tray.

Login startup is off by default and can be enabled from GamepadKey's settings.

Troubleshooting

The window stays on “Starting input service”

An older instance may still be running after an upgrade. Stop it and start a fresh copy:

pkill -x gamepadkey
gamepadkey

The controller is not detected

Check that xpadneo is loaded and that Linux sees the controller:

lsmod | grep hid_xpadneo
grep -A5 -B2 "Xbox Wireless Controller" /proc/bus/input/devices

Disconnecting and reconnecting the controller after permission setup may also refresh its access rules.

Buttons work elsewhere but not in GamepadKey

Use evtest to confirm which event device belongs to the controller:

sudo apt install evtest
evtest

Select Xbox Wireless Controller from the displayed list and press a few buttons. If events appear there but not in GamepadKey, restart GamepadKey using the command above.

For developers

Install the build tools on Ubuntu 24.04:

sudo apt install build-essential pkg-config libgtk-4-dev libadwaita-1-dev libudev-dev

Build, test, and run directly from the source tree:

cargo build
cargo test
./target/debug/gamepadkey

When running without installing the package, the first-launch permission helper can be started manually:

pkexec ./data/gamepadkey-setup

Build the Debian package with:

dpkg-buildpackage -b -us -uc

License

GamepadKey is free software licensed under GPL-3.0-or-later.