Installation

Installation

Requirements

• The kernel driver hid-lg-g15 must drive the device. The G13 needs Linux 6.19 or newer; G15, G15 v2 and G510 are supported by the kernel since Linux 5.5, the G11 since Linux 5.7.
• The packages are built for distribution releases that ship Linux 6.19 or newer.
• Target desktops are KDE Plasma and GNOME on Wayland; nothing below the application depends on the display server.

Packages

Packages are attached to every GitHub release:

System	Package
Ubuntu 26.04 and derivatives based on it (Linux Mint, Pop!_OS, …)	gkey-config_<version>-1.ubuntu26.04_amd64.deb
Fedora 44	gkey-config-<version>-1.fc44.x86_64.rpm
Arch Linux and derivatives	AUR: gkey-config
SteamOS 3.9 or newer (Steam Deck)	gkey-config-<version>-steamos-x86_64.tar.gz with install script, see Steam Deck

# Ubuntu
sudo apt install ./gkey-config_<version>-1.ubuntu26.04_amd64.deb
# Fedora
sudo dnf install ./gkey-config-<version>-1.fc44.x86_64.rpm
# Arch Linux, with an AUR helper such as yay or paru
yay -S gkey-config

The package manager installs all dependencies. Recommended packages are installed by default as well: pkexec/polkit (LED access from the application), the Qt Wayland plugin and xdg-utils.

gkey-config conflicts with linux-g13-driver, which drives the G13 with its own libusb driver; the package manager removes the old driver or asks you to. gkey-config is its successor for kernels with G13 support in hid-lg-g15.

First start

Open G-Key Configuration from the application menu. On its first start it offers to

• start the daemon at every login (systemctl --user enable --now gkeyd for your user), and
• allow LED control by adding your user to the group gkey. The system asks for the administrator password; log out completely and back in afterwards.

Both can be changed at any time in the Settings menu, together with Show the tray icon at login. All three settings apply to your user only.

What gets installed

Part	Role
gkeyd (systemd user service)	grabs the gaming-key input devices, applies the bindings, drives LEDs and LCD
gkey-config	configuration application and tray icon
70-gkey-config.rules (udev)	gives the user of the active local session access to the devices and /dev/uinput (uaccess)
group gkey	LED attributes in sysfs cannot carry ACLs; members of this group may change them

Without membership in gkey everything except the LEDs works. To add a user by hand: sudo usermod -aG gkey $USER, then log out completely and back in.

On keyboards (G11, G15, G15 v2, G510) the udev rule only opens the interface with the gaming keys and the LCD; the normal keyboard is never touched.

Security note: /dev/uinput

The daemon sends the configured keys through a virtual input device, so the udev rule gives the logged-in user access to /dev/uinput. With that access every program of this user can create virtual keyboards and type into any window, including password prompts. On Wayland this bypasses the separation of input that the compositor otherwise provides. Steam's controller support needs and grants the same access.

Only programs running as your user can use it; other users of the computer cannot. If that is not acceptable on a computer, do not install gkey-config there.

Hardening of the daemon

The systemd user unit restricts the daemon to the system calls of normal services, to local sockets (D-Bus, udev events), without new privileges; files it creates are only readable by your user.

Upgrade and removal

After an upgrade, restart a running daemon: systemctl --user restart gkeyd.

Remove the package with sudo apt remove gkey-config, sudo dnf remove gkey-config or sudo pacman -R gkey-config. Profiles and macros stay in ~/.config/gkey-config/.

Building from source

See CONTRIBUTING.md for dependencies, build options, tests and translations. In short:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr
cmake --build build
sudo cmake --install build