Jump to content

# Xorg/Keyboard configuration

From ArchWiki
< Xorg

Related articles

- X keyboard extension
- Linux console/Keyboard configuration
- Extra keyboard keys
- Xorg
- Keyboard shortcuts

This article describes the basics of Xorg keyboard configuration. For advanced topics such as keyboard layout modification or additional key mappings, see X keyboard extension or Extra keyboard keys respectively.

The Xorg server uses the X keyboard extension (XKB) to define keyboard layouts. Optionally, xmodmap can be used to access the internal keymap table directly, although this is not recommended for complex tasks. Also systemd's localectl can be used to define the keyboard layout for both the Xorg server and the virtual console.

Note XKB options can be overridden by the tools provided by some desktop environments such as GNOME and Plasma.

## Viewing keyboard settings

You can use the following command to see the actual XKB settings:

    $ setxkbmap -print -verbose 10

    Setting verbose level to 10
    locale is C
    Applied rules from evdev:
    model:      evdev
    layout:     us
    options:    terminate:ctrl_alt_bksp
    Trying to build keymap using the following components:
    keycodes:   evdev+aliases(qwerty)
    types:      complete
    compat:     complete
    symbols:    pc+us+inet(evdev)+terminate(ctrl_alt_bksp)
    geometry:   pc(pc104)
    xkb_keymap {
            xkb_keycodes  { include "evdev+aliases(qwerty)" };
            xkb_types     { include "complete"      };
            xkb_compat    { include "complete"      };
            xkb_symbols   { include "pc+us+inet(evdev)+terminate(ctrl_alt_bksp)"    };
            xkb_geometry  { include "pc(pc104)"     };
    };

### Third party utilities

There are some "unofficial" utilities which allow to print specific information about the currently used keyboard layout.

- xkb-switch-gitAUR:

    $ xkb-switch

    us

- xkblayout-state-gitAUR:

    $ xkblayout-state print "%s"

    de

## Setting keyboard layout

Keyboard layout in Xorg can be set in multiple ways. Here is an explanation of used options:

- `XkbModel` selects the keyboard model. This has an influence only for some extra keys your keyboard might have. The safe fallback are `pc104` (ANSI) or `pc105` (ISO). But for instance laptops usually have some extra keys, and sometimes you can make them work by simply setting a proper model.
- `XkbLayout` selects the keyboard layout. Multiple layouts may be specified in a comma-separated list, e.g. if you want to quickly switch between layouts.
- `XkbVariant` selects a specific layout variant available for the `XkbLayout`. For instance, the default `sk` (Slovak) variant is `qwertz`, but you can manually specify `qwerty`, etc.
- `XkbOptions` contains some extra options (comma-separated). Used for specifying layout switching, notification LED, compose mode etc. See the #Frequently used XKB options section for examples.

Note You must specify as many variants as the number of specified layouts. If you want the default variant, specify an empty string as the variant (the comma must stay). For example, to have the default `us` layout as primary and the `dvorak` variant of `us` layout as secondary, specify `us,us` as `XkbLayout` and `,dvorak` as `XkbVariant`.

The layout name is usually a 2-letter country code. To see a full list of keyboard models, layouts, variants and options, along with a short description, open `/usr/share/X11/xkb/rules/base.lst`. Alternatively, you may use one of the following commands to see a list without a description:

- `localectl list-x11-keymap-models`
- `localectl list-x11-keymap-layouts`
- `localectl list-x11-keymap-variants [layout]`
- `localectl list-x11-keymap-options`

Examples in the following subsections will have the same effect, they will set `pc104` model, `cz` as primary layout, `us` as secondary layout, `dvorak` variant for `us` layout and the `Super+Space` combination for switching between layouts. See xkeyboard-config(7) for more detailed information.

Note Fcitx/IBus users may find these methods not working, or just work for a while, since they will try to control keyboard layout. Fcitx users need to set the first input method to be `Keyboard - layout`. See Fcitx#Input methods configuration. IBus users need to enable "Use system keyboard layout" option in Preference -> Advanced if using X configuration files, or manually specify the layout if using setxkbmap.

### Using X configuration files

Note `xorg.conf` is parsed by the X server at start-up. To apply changes, restart X.

The syntax of X configuration files is explained in Xorg#Configuration. This method creates system-wide configuration which is persistent across reboots.

Here is an example:

    /etc/X11/xorg.conf.d/00-keyboard.conf

    Section "InputClass"
            Identifier "system-keyboard"
            MatchIsKeyboard "on"
            Option "XkbLayout" "cz,us"
            Option "XkbModel" "pc104"
            Option "XkbVariant" ",dvorak"
            Option "XkbOptions" "grp:win_space_toggle"
    EndSection

#### Using localectl

For convenience, the tool localectl may be used instead of manually editing X configuration files. It will save the configuration in `/etc/X11/xorg.conf.d/00-keyboard.conf`, this file should not be manually edited, because localectl will overwrite the changes on next start.

The usage is as follows:

    # localectl [--no-convert] set-x11-keymap layout [model [variant [options]]]

To set a model, variant or options, all preceding fields need to be specified, but the preceding fields can be skipped by passing an empty string with `""`. Unless the `--no-convert` option is passed, the specified keymap is also converted to the closest matching console keymap and applied to the console configuration in `vconsole.conf`. See localectl(1) for more information.

To create a `/etc/X11/xorg.conf.d/00-keyboard.conf` like the above:

    # localectl --no-convert set-x11-keymap cz,us pc104 ,dvorak grp:win_space_toggle

Tip localectl additionally writes the keyboard configuration to `/etc/vconsole.conf` using variables `XKBLAYOUT`, `XKBMODEL`, `XKBVARIANT` and `XKBOPTIONS`, [1] but the Xorg server does not read them from that file.

### Using setxkbmap

This article or section needs expansion.

Reason: Udev also comes into play (for example when plugging in a keyboard), undoing changes by setxkbmap (Discuss in Talk:Xorg/Keyboard configuration#Persisting layout when USB keyboard connected)

setxkbmap sets the keyboard layout for the current X session only, but can be made persistent in xinitrc or xprofile. This overrides system-wide configuration specified following #Using X configuration files.

The usage is as follows (see setxkbmap(1)):

    $ setxkbmap [-model xkb_model] [-layout xkb_layout] [-variant xkb_variant] [-option xkb_options]

Note setxkbmap adds options specified in the command line to the options that were set before (as saved in root window properties). If you want to replace all previously specified options, use the `-option` flag with an empty argument first.

To change just the layout (`-layout` is the default flag):

    $ setxkbmap xkb_layout

For multiple customizations:

    $ setxkbmap -model pc104 -layout cz,us -variant ,dvorak -option grp:win_space_toggle

## Frequently used XKB options

### Switching between keyboard layouts

To be able to easily switch keyboard layouts, first specify multiple layouts between which you want to switch (the first one is the default). Then specify a key (or key combination), which will be used for switching. For example, to switch between a US and a Swedish layout using the `CapsLock` key, use `us,se` as an argument of `XkbLayout` and `grp:caps_toggle` as an argument of `XkbOptions`. The number of `XkbLayout`s should match that of the `XkbVariant`s — if you want to switch solely between different variants, then duplicate the layout accordingly (e.g. `de,de`).

The list of available layouts (and variants) can be found in xkeyboard-config(7) § LAYOUTS. The key combinations available for layout switching are listed in xkeyboard-config(7) § Switching to another layout.

Note that the `grp:alts_toggle` option is unreliable and unlikely to be fixed; prefer other combinations.

#### Switch languages using Alt Shift

To set `Alt+Shift` as a layout shortcut, use `grp:alt_shift_toggle` in `XkbOptions`.

However, there is a known issue with XKB that causes other shortcuts of the type `Alt+Shift+any_key` to break. Moreover, XKB may set the right `Alt` to be `AltGr` by default in some keyboard layouts, making `RAlt+RShift` not working for layout switching.

As a workaround, sxhkd may be used to switch layouts by adding the following to `sxhkdrc`:

    Shift_L + Alt_L
        setxkbmap -query | grep -q 'fr' && setxkbmap us || setxkbmap fr,us
    Shift_R + Alt_R
        setxkbmap -query | grep -q 'fr' && setxkbmap us || setxkbmap fr,us

Note that for some reason, `Alt` must be pressed before `Shift` to be detected by sxhkd.

### Terminating Xorg with Ctrl+Alt+Backspace

By default, the key combination `Ctrl+Alt+Backspace` is disabled. You can enable it by passing `terminate:ctrl_alt_bksp` to `XkbOptions`. This can also be done by binding a key to `Terminate_Server` in `xmodmap` (which undoes any existing `XkbOptions` setting). In order for either method to work, one also needs to have `DontZap` set to "off" in `ServerFlags`: since 2004 [2] this is the default.

### Swapping Caps Lock with Left Control

To swap Caps Lock with Left Control key, add `ctrl:swapcaps` to `XkbOptions`. Run the following command to see similar options along with their descriptions:

    $ grep -E "(ctrl|caps):" /usr/share/X11/xkb/rules/base.lst

### Enabling mouse keys

Mouse keys, not to be confused with the keys of the mouse, is disabled by default and has to be manually enabled by passing `keypad:pointerkeys` to `XkbOptions`. This will make the `Shift+NumLock` shortcut toggle mouse keys.

See also X keyboard extension#Mouse control for advanced configuration.

### Configuring AltGr

The AltGr (Alternate Graphic) key can be used to access additional characters and symbols on a keyboard. It functions as a modifier key similar to Shift but provides access to a third level of key mappings. Note that mapping levels work as follows:

- 1st Level: Default layer of keys (no modifier).
- 2nd Level: Accessed by pressing the Shift key, providing secondary characters (e.g. capitalization) or symbols (e.g. @ symbol).
- 3rd Level: Accessed by pressing the AltGr key, allowing access to additional characters or symbols not available on the 1st and 2nd levels.

2nd level characters are usually printed on keyboard keys and are easy to find. On the other hand, to check the characters on additional levels, you can use `xmodmap -pk` or look up your keyboard mapping on `/usr/share/X11/xkb/symbols`.

### Configuring compose key

Though typically not on traditional keyboards, a Compose key can be configured to an existent key.

The `Compose` key begins a keypress sequence that involves (usually two) additional keypresses. Usage is typically either for entering characters in a language that the keyboard was not designed for, or for other less-used characters that are not covered with the `AltGr` modifier. For example, pressing `Compose` `'` `e` produces `é`, or `Compose` `-` `-` `-` will produce an "em dash": `—`.

Though a few more eccentric keyboards feature a `Compose` key, its availability is usually through substituting an already existing key to it. For example, to make the `Menu` key a `Compose` key use the Desktop environment configuration, or pass `compose:menu` to `XkbOptions` (or setxkbmap: `setxkbmap -option compose:menu`). Allowed key substitutions are defined in `/usr/share/X11/xkb/rules/base.lst`:

    $ grep "compose:" /usr/share/X11/xkb/rules/base.lst

If the desired mapping is not found in that file, an alternative is to use xmodmap to map the desired key to the `Multi_key` keysym, which acts as a compose key by default (note that xmodmap settings are reset by setxkbmap).

#### Key combinations

The default combinations for the compose keys depend on the locale configured for the session and are stored in `/usr/share/X11/locale/used_locale/Compose`, where `used_locale` is for example `en_US.UTF-8`.

You can define your own compose key combinations by copying the default file to `~/.XCompose` and editing it. Alternatively, create an empty `~/.XCompose` and include the default one using `include "%L"`, for example:

    ~/.XCompose

    include "%L"

    <Multi_key> <g> <a> : "α"
    <Multi_key> <g> <b> : "β"
    <Multi_key> <g> <g> : "γ"

The compose key (denoted as `<Multi_key>` in the `~/.XCompose` file) works with any of the thousands of valid Unicode characters, including those outside the Basic Multilingual Plane. Take a look at the Compose(5) man page, it explains the format of the XCompose files.

However, GTK does not use XIM by default and therefore does not follow `~/.XCompose` keys. This can be fixed by forcing GTK to use XIM by configure the graphical environment variables `GTK_IM_MODULE=xim` and/or `XMODIFIERS="@im=none"`.

Tip XIM is very old, you might have better luck with other input methods such as IBus and Fcitx5; see Input method for details.
Note XIM will prevent insertion of Unicode characters with the `Ctrl+Shift+u` combination.

### Currency sign on other key

Most European keyboards have a Euro sign (€) printed on on the `5` key. For example, to access it with `Alt+5`, use the `lv3:ralt_switch` and `eurosign:5` options.

The Rupee sign (₹) can be used the same way with `rupeesign:4`.

### Switching state immediately when Caps Lock is pressed

Those who prefer typing capital letters with the Caps Lock key may experience a short delay when Caps Lock state is switched, resulting in two or more capital letters (e.g. THe, ARch LInux). This occurs because Caps Lock is enabled immediately once the Caps Lock key is pressed, but is only disabled upon release of the second key-press. This behaviour stems from typewriters where a Caps Lock function was achieved by physically locking the shifted typebars in place, and the release of a shift key-press was the action that caused the release of the lock.

Some more popular operating systems have removed this behaviour, either voluntarily (as it can be confusing to some) or by mistake, however this is a question of preference. Bug reports have been filed on the Xserver bug tracker, as there is currently no easy way to switch to the behaviour reflected by those other operating systems. For anyone who would like to follow up the issue, bug reports and latest working progress can be found at [3] and [4].

#### Workaround

First, export your keyboard configurations to a file:

    $ xkbcomp -xkb $DISPLAY xkbmap

In the file xkbmap, locate the Caps Lock section which begins with key <CAPS>:

     key <CAPS> {         [       Caps_Lock ] };

and replace whole section with the following code:

    key <CAPS> {
        repeat=no,
        type[group1]="ALPHABETIC",
        symbols[group1]=[ Caps_Lock, Caps_Lock],
        actions[group1]=[ LockMods(modifiers=Lock), Private(type=3,data[0]=1,data[1]=3,data[2]=3)]
    };

Save and reload keyboard configurations:

    $ xkbcomp -w 0 xkbmap $DISPLAY

Consider making it a service launching after X starts, since reloaded configurations do not survive a system reboot.

## One-click key functions

To assign an additional one-click function to a modifier key, you can use xcape. For example it is possible to have `CapsLock` work as `Escape` when pressed alone, and as `Control` when used with another key. First set the `Control` swapping using setxkbmap as mentioned earlier, and xcape to set the `Escape` association:

    $ xcape -e 'Caps_Lock=Escape'

You can set multiple associations separated with a semicolon, e.g.: `Caps_Lock=Escape;Shift_L=Escape`.

If you hold a key for longer than the timeout value (default 500 ms), xcape will not generate a key event.

## Adjusting typematic delay and rate

The typematic delay indicates the amount of time (typically in milliseconds) a key needs to be pressed and held in order for the repeating process to begin. After the repeating process has been triggered, the character will be repeated with a certain frequency (usually given in Hz) specified by the typematic rate. Note that these settings are configured separately for Xorg and for the virtual console.

### Using xset

The tool xset, provided by xorg-xset, can be used to set the typematic delay and rate for an active X server, though certain actions during runtime may cause the X server to reset these changes and revert instead to its seat defaults.

Usage:

    $ xset r rate delay [rate]

For example to set a typematic delay to 200ms and a typematic rate to 30Hz, use the following command:

    $ xset r rate 200 30

Issuing the command without specifying the delay and rate will reset the typematic values to their respective defaults; a delay of 660ms and a rate of 25Hz:

    $ xset r rate

### Using xautocfg

xautocfgAUR can apply repeat rate settings for newly connected devices automatically. It watches for X11 events and applies repeat rate configuration to newly connected keyboards.

Adjust the configuration:

    ~/.config/xautocfg.cfg

    [keyboard]

    # repeat delay in ms
    delay = 200

    # repeat rate in Hz
    rate = 30

If `graphical-session.target` is started by your window manager or desktop environment, enable the systemd/User `xautocfg.service`. Alternatively, launch `xautocfg` manually.

### Using AutoRepeat configuration option

To persist the configuration system-wide, change the seat defaults with an Xorg configuration file as described in #Using X configuration files, and add a `AutoRepeat` section entry: [5]

The parameters for `AutoRepeat` are `delay` and `interval` in milliseconds. If you like 25 Hz `rate` of xset, the corresponding `interval` 1000 / 25 = 40 milliseconds.

    /etc/X11/xorg.conf.d/00-keyboard.conf

    Section "InputClass"
            ...
            Option "AutoRepeat" "200 40"
            ...
    EndSection

### Using XServer startup options

Another method of persisting the configuration is to pass the desired settings to the X server on its startup using the following options:

- `-ardelay milliseconds` - sets the autorepeat delay (length of time in milliseconds that a key must be depressed before autorepeat starts).
- `-arinterval milliseconds` - sets the autorepeat interval (length of time in milliseconds that should elapse between autorepeat-generated keystrokes).

See Xserver(1) for a full list of X server options and refer to your display manager for information about how to pass these options.

## Manually crafting a new layout

To manually modify or create a layout, some low-level knowledge is needed.

To physical keys, numbers assigned by kernel. They are listed in `/usr/include/linux/input-event-codes.h`, provided linux-api-headers—a dependency of linux-headers—is installed, like this:

    #define KEY_Q			16
    #define KEY_W			17
    ...
    #define KEY_LEFTBRACE		26
    #define KEY_RIGHTBRACE		27

These values are used by libevdev. For input remap utilities that rely on libevdev, key names are often these entries in lowercase, without the prefix `KEY_`. Xorg's "keycode" value is the one in the file `input-event-codes.h` + 8. (For example `KEY_Q` is 16. The X's keycode of the key printed "Q" 24.)

In XKB however, i.e. for X and Wayland, the key names look like `<AD11>` or `<TLDE>`. Most of them are easy to guess; for example if you have an Italian keyboard, just look at `/usr/share/X11/xkb/symbols/it`. It has the lines:

    key <TLDE>  {[ backslash,        bar,        notsign,       brokenbar ]};
    key <AD11>  {[    egrave,     eacute,    bracketleft,       braceleft ]};

When it is not sufficient, look at files in `/usr/share/X11/xkb/keycodes`, in particular the file `evdev`. These lines define the keycode for the key name.

    <TLDE> = 49;
    <AD11> = 34;

Finally, what are possible symbols that can be assigned to keys, like `notsign` or `brokenbar` in the above example? They are defined in `/usr/include/X11/keysymdef.h`

    #define XK_brokenbar                     0x00a6  /* U+00A6 BROKEN BAR */
    #define XK_notsign                       0x00ac  /* U+00AC NOT SIGN */

Some symbols with the prefix XF86 is listed in the separate file `/usr/include/X11/XF86keysym.h`.

    #define XF86XK_MonBrightnessUp       0x1008ff02  /* Monitor/panel brightness */

This key is called `XF86MonBrightnessUp` in X. (Again rip off XK_, but in such cases the middle of the name.)

## See also

- Madduck guide on extending XKB (archived at Wayback Machine)
- How to modify a keyboard layout in Linux - Romano Giannetti's blog

Categories:

- X server
- Keyboard configuration

Hidden category:

- Pages or sections flagged with Template:Expansion

Xorg/Keyboard configuration
Add topic