libxkbcommon is a keyboard keymap compiler and support library which processes keymaps as defined by the XKB (X Keyboard Extension) specification (minus some legacy features). It also contains a module for handling Compose and dead keys, a separate registry library for listing available keyboard layouts and a fair set of CLI tools to support keyboard layouts development.

libxkbcommon is the standard keymap handling library on Wayland and is used by compositors, toolkits, and applications to handle keyboard state and translate key events into characters and actions.

Quick Guide

Introduction to XKB

See Introduction to XKB for the essentials of XKB concepts and how a keymap is built.

Using the library

Library quick guide: Introduction on how to use this library
API Documentation: Full API reference
Release notes: History of the libxkbcommon changes by version
FAQ: Frequently Asked Questions

Developing keyboard layouts

Custom layouts: Quick start for adding a custom layout or option
Keymap format: Documentation of keymap components and keymap text syntax
Tools: Introduction to the xkbcli application
FAQ: Frequently Asked Questions

Building

libxkbcommon requires:

a C compiler supporting C11
XKB registry (optional): libxml2
X11 features (optional): libxcb and libxcb-xkb
Wayland features (optional): wayland-client, wayland-protocols, wayland-scanner

libxkbcommon is built with Meson:

meson setup build
meson compile -C build
meson test -C build # Run the tests.

To build for use with Wayland, you can disable X11 support while still using the X11 keyboard configuration resource files thusly:

meson setup build \
      -Denable-x11=false \
      -Dxkb-config-root=/usr/share/X11/xkb \
      -Dx-locale-root=/usr/share/X11/locale
meson compile -C build

Complete list of user options

option(
    'xkb-config-root',
    type: 'string',
    description: 'The XKB config root [default=xkeyboard-config install path]',
)
option(
    'xkb-config-versioned-extensions-path',
    type: 'string',
    description: 'Lookup path for system-wide XKB versioned data extensions [default=xkeyboard-config install path + .d]',
)
option(
    'xkb-config-unversioned-extensions-path',
    type: 'string',
    description: 'Lookup path for system-wide XKB unversioned data extensions [default=xkeyboard-config install path - version + .d]',
)
option(
    'xkb-config-extra-path',
    type: 'string',
    description: 'Extra lookup path for system-wide XKB data [default=$sysconfdir/xkb]',
)
option(
    'x-locale-root',
    type: 'string',
    description: 'The X locale root [default=$datadir/X11/locale]',
)
option(
    'bash-completion-path',
    type: 'string',
    description: 'Directory for bash completion scripts'
)
option(
    'default-rules',
    type: 'string',
    value: 'evdev',
    description: 'Default XKB ruleset',
)
option(
    'default-model',
    type: 'string',
    value: 'pc105',
    description: 'Default XKB model',
)
option(
    'default-layout',
    type: 'string',
    value: 'us',
    description: 'Default XKB layout',
)
option(
    'default-variant',
    type: 'string',
    value: '',
    description: 'Default XKB variant',
)
option(
    'default-options',
    type: 'string',
    value: '',
    description: 'Default XKB options',
)
option(
    'enable-tools',
    type: 'boolean',
    value: true,
    description: 'Enable building tools',
)
option(
    'enable-x11',
    type: 'boolean',
    value: true,
    description: 'Enable building the xkbcommon-x11 library',
)
option(
    'enable-docs',
    type: 'boolean',
    value: false,
    description: 'Enable building the documentation',
)
option(
    'enable-cool-uris',
    type: 'boolean',
    value: false,
    description: 'Enable creating redirections to maintain stable documentation pages',
)
option(
    'enable-wayland',
    type: 'boolean',
    value: true,
    description: 'Enable support for Wayland utility programs (requires enable-tools)',
)
option(
    'enable-xkbregistry',
    type: 'boolean',
    value: true,
    description: 'Enable building libxkbregistry',
)
option(
    'enable-bash-completion',
    type: 'boolean',
    value: true,
    description: 'Enable installing bash completion scripts',
)

API

While libxkbcommon’s API is somewhat derived from the classic XKB API as found in X11/extensions/XKB.h and friends, it has been substantially reworked to expose fewer internal details to clients.

See the API Documentation.

Tools

Libxkbcommon offers a set of CLI tools, grouped under the xkbcli application:

xkbcli compile-keymap: Compile an XKB keymap
xkbcli compile-compose: Compile a compose file
xkbcli how-to-type: Show how to type a given Unicode codepoint
xkbcli interactive-wayland: Interactive debugger for XKB keymaps for Wayland
xkbcli interactive-x11: Interactive debugger for XKB keymaps for X11
xkbcli interactive-evdev: Interactive debugger for XKB keymaps for evdev
xkbcli dump-keymap-wayland: Dump an XKB keymap from a Wayland compositor
xkbcli dump-keymap-x11: Dump an XKB keymap from an X server
xkbcli list: List available layouts and more

It may require the installation of the package libxkbcommon-tools or similar name.

Layouts database

libxkbcommon does not distribute a keyboard layout dataset itself, other than for testing purposes. The most common dataset is xkeyboard-config, which is used by all current distributions for their XKB data. Further information on xkeyboard-config is available at its homepage and at its repository.

The dataset for Compose is distributed in libX11, as part of the X locale data.