Skip to main content

Linux keyboard mapping utility

Project description


Linux keyboard mapping utility


Mapping physical keyboard keys under Linux system is tricky. Since there is multiple places where you can interrupt and handle keystroke, there is a ton of solutions for different levels. KBMAP focuses on handling keystroke straight from the physical device, before converting keycode to the keysym (it's a place, where windowing system applies keyboard layouts and locales).

KBMAP allows you to apply flexible configurations directly to the keyboard input device without writing a mess of C code or breaking system config files.

KBMAP is heavily inspired by QMK - highly customizable mechanical keyboard firmware. Basically, ideally KBMAP will be the QMK of any non-programmable keyboard (and maybe not only keyboard).


pip install kbmap



  Create virtual device that will remap keyboard events from device with

  --version          Show the version and exit.
  -c, --config TEXT  Mapping configuration path.
  -n, --name TEXT    Name of the virtual device that will write events.
  -v, --verbose      Print detailed logs.
  --help             Show this message and exit.


Q: How it works?
A: KBMAP uses evdev - a Linux input event interface. There is python binding for evdev library: python-evdev. Mapping algorithm:

  1. Find a target device by name (specified with DEVICE_NAME argument)
  2. Create new uinput device (kind of a virtual input device) with specified name (--name option)
  3. Grab target device (so only KBMAP process receive input events)
  4. Listen for key events from target device
  5. Perform remapping based on config file (specified with CONFIG_PATH argument)
  6. Dispatch events through created uinput device

Q: Linux only?
A: Yes, since evdev is a specific Linux interface, KBMAP cannot be used on non-unix operating systems.

Q: Alternatives for Windows?
A: AutoHotkey.

Q: How is KBMAP related to QMK?
A: QMK has a lot of mapping features. But QMK is a firmware and you cannot use it unless your keyboard is programmable. The mind behind KBMAP is to allow non-programmable keyboard users to achieve QMK-like customizability with their input device. Current goal is to reach TMK (a program, QMK being forked from) functionality.

Q: I am getting UInputError: "/dev/uinput" cannot be opened for writing.
A: Solution.

Q: How to run KBMAP at system boot?
A: It can be done in several ways, check out stackoverflow question and Arch Linux wiki page.

Q: What features are already implemented?
Q: How to configure KBMAP?
Q: KBMAP keycodes?
A: See wiki.


Documentation and useful resources can be found in wiki.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

kbmap-1.1.0.tar.gz (16.7 kB view hashes)

Uploaded source

Built Distribution

kbmap-1.1.0-py3-none-any.whl (23.0 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page