Remap one key to another in Linux, like Capslock to Control

Linux is known for choice and customizability.

So it's ironic but when it comes to keyboard and mouse key remapping and scripting, Linux is the more challenging than Windows (using AutoHotKey) or Macs (using Karabiner-Elements).

I'll link to some guides and answers below, but some big picture ideas to be aware of in 2020 for Linux key remapping:

xmodmap is deprecated

Prefer using setxkbmap if it'll do what you want.

Some xmodmap functionality remains, but it's clearly a deprecated system and it sometimes doesn't work.

I tried to do some simple key remapping with it on Debian LXDE and it didn't work for me.

setxkbmap is preferred but complicated

It has many common remappings like turning capslock to control [1]:

setxkbmap -option -option caps:ctrl_modifier

The first blank "-option" clears any previously set.  Then the second option sets the capslock to control.

Swapping the left control and alt keys can be easy to do as there's a direct option for it too.

Running setxkbmap only affects the current session, so logging out will wipe the settings. To make it auto set on login, put it in a script run from .bashrc or similar.


But what if you want to swap the right control and alt keys instead?  Or some weird 4 way switch of keys?

There many be some set of xkeyboard-config options that'll work, but it's not straightforward the way it is on a Mac with Karabiner-Elements.

You also may have to find and use keycodes or events generated by your keyboard or mouse interactively.  Do this using the xev command line app [3].

 If you want to go down this route, be sure to check out:  A simple, humble but comprehensive guide to XKB for linux.  But if you want an easier way, check out the last section below because, of course, there's an app for that!

Show setxkbmap options

To find what options are supported by setxkbmap, you can run [2]:

man xkeyboard-config

man xkeyboard-config is not complete: e.g. right alt to right control

More annoyingly, turns out running man xkeyboard-config does not list a complete list of what setxkbmap can do!

For example, let's say you want to make the right alt another right control key.

It's not listed in man xkeyboard-config but it is easily possible!  Just run:

setxkbmap -option ctrl:ralt_rctrl

It is listed in a lower level description file at however [4] :


And if you're up to it, you can change the low level description files that setxkbmap uses to give you great control over the keyboard remappings.  But it's not easy the way it is on Macs and Windows!

Remapping single keys using hwdb files

This is lower level than setxkbmap, but it's not deprecated like xmodmap, and for single key to single key remapping, it seems to work well.

Detailed instructions found at: Remapping keys using hwdb files

Use an app to intercept and inject keys

This method allows more complex hotkeys and combos to be remapped to almost arbitrary input.

This is really new.  Try out  sezanzeb's key-mapper.  It works with X11 and Wayland, and has an easy GUI interface to it.

Here's a nice guide for it: Remap Keyboard And Mouse Buttons On Linux With The New Key Mapper GUI (Supports X11 And Wayland).

Since key-mapper is a Python program, you'll need Python to run it anyway.  So on Debian, you might as well just install Python and pip, then use pip to install it.

Key-mapper is not available in Debian's package system, so you'll have to download and install it from the key-mapper Github repository.

In fact, Debian has a package called "keymapper" that is not the key-mapper you're looking for.  Using apt to install key-mapper, even key-mapper's own pre-packaged .deb file, kept suggesting the wrong "keymapper" package instead.

Probably easiest to just install it with pip!

(NEW!)  Check out kinto if you're interested in mac-style hotkeys on Linux and Windows!


[1] How to swap Ctrl and Caps Lock keys in Linux

[2] List all valid kbd layou ts, variants and toggle options (to use with setxkbmap)

[3] How to prevent the caps-lock toggle effect, without remapping or disabling it?

[4] Map right alt to left control

No comments: