The majority of user-specific configurations involve modifying key symbols and this is what this document focuses on. For use-cases where a user may need to add new key types or compat entries the general approach remains the same. A detailed description for how to add those types or compat entries is out of scope for this document.

You should never need to add user-specific keycodes. Where a keycode is missing, the addition should be filed in the upstream xkeyboard-config project.

RMLVO vs KcCGST

Due to how XKB is configured, there is no such thing as a “layout” in XKB itself, or, indeed, any of the rules, models, variant, options (RMLVO) described in struct xkb_rule_names. RMLVO names are merely lookup keys in the rules file provided by xkeyboard-config to map to the correct keycode, compat, geometry (ignored by libxkbcommon), symbols and types (KcCGST). The KcCGST data is the one used by XKB and libxkbcommon to map keys to actual symbols.

For example, a common RMLVO configuration is layout us, variant dvorak and option terminate:ctrl_alt_bksp. Using the default rules file and model this maps into the following KcCGST components:

Output of the command: xkbcli compile-keymap --kccgst --layout us --variant dvorak --options terminate:ctrl_alt_bksp

xkb_keymap {
    xkb_keycodes  { include "evdev+aliases(qwerty)" };
    xkb_types     { include "complete"  };
    xkb_compat    { include "complete"  };
    xkb_symbols   { include "pc+us(dvorak)+inet(evdev)+terminate(ctrl_alt_bksp)"    };
    xkb_geometry  { include "pc(pc105)" };
};

A detailed explanation of how rules files convert RMLVO to KcCGST is out of scope for this document. See the rules file page instead.

Adding a layout requires that the user adds symbols in the correct location.

The default rules files (usually evdev) have a catch-all to map a layout, say foo, and a variant, say bar, into the bar section in the file <datadir>/X11/xkb/symbols/foo. This is sufficient to define a new keyboard layout. The example below defines the keyboard layout banana with an optional variant orange:

Content of $XDG_CONFIG_HOME/xkb/symbols/banana

// Like a US layout but swap the top row so numbers are on Shift
default partial alphanumeric_keys
xkb_symbols "basic" {
    include "us(basic)"
    name[Group1]= "Banana (US)";
    key <AE01> { [ exclam,          1]     };
    key <AE02> { [ at,              2]     };
    key <AE03> { [ numbersign,      3]     };
    key <AE04> { [ dollar,          4]     };
    key <AE05> { [ percent,         5]     };
    key <AE06> { [ asciicircum,     6]     };
    key <AE07> { [ ampersand,       7]     };
    key <AE08> { [ asterisk,        8]     };
    key <AE09> { [ parenleft,       9]     };
    key <AE10> { [ parenright,      0]     };
    key <AE11> { [ underscore,      minus] };
    key <AE12> { [ plus,            equal] };
};
// Same as banana but map the euro sign to the 5 key
partial alphanumeric_keys
xkb_symbols "orange" {
    include "banana(basic)"
    name[Group1] = "Banana (Eurosign on 5)";
    include "eurosign(5)"
};

The default section is loaded when no variant is given. The first example sections uses include to populate with a symbols list defined elsewhere (here: section basic from the file symbols/us, aka. the default US keyboard layout) and overrides parts of these symbols. The effect of this section is to swap the numbers and symbols in the top-most row (compared to the US layout) but otherwise use the US layout.

The orange variant uses the banana symbols and includes a different section to define the eurosign. It does not specifically override any symbols.

The exact details of how xkb_symbols section works is out of scope for this document; see: The XKB keymap text format, V1 and V2.

Remarks: This example uses a file name banana that should not clash with the system files in <datadir>/X11/xkb/symbols. Using the same file name than the system files is possible but may require special handling, see: Using system file names.

For technical reasons, options do not have a catch-all to map option names to files and sections and must be specifically mapped by the user. This requires a custom rules file. As the evdev ruleset is hardcoded in many clients, the custom rules file must usually be named evdev.

Content of $XDG_CONFIG_HOME/xkb/rules/evdev

 // Mandatory to extend the
 ! include %S/evdev
 
 ! option     = symbols
   custom:foo = +custom(bar)
   custom:baz = +other(baz)

The include statement includes the system-provided evdev ruleset. This allows users to only override those options they need afterwards.

This rules file maps the RMLVO option custom:foo to the bar section in the symbols/custom file and the custom:baz option to the baz section in the symbols/other file. Note how the RMLVO option name may be different to the file or section name.

The order of the options matters! In this example, custom:foo will always be applied before custom:baz and both options will always be applied after the system ones, even if the order is different in the RMLVO configuration passed to libxkbcommon (e.g. with xkbcli). See the related section in the rules documentation for further details.

The files themselves are similar to the layout examples in the previous section:

Content of $XDG_CONFIG_HOME/xkb/symbols/custom

// map the Tilde key to nothing on the first shift level
partial alphanumeric_keys
xkb_symbols "bar" {
    key <TLDE> {        [      VoidSymbol ]       };
};

Content of $XDG_CONFIG_HOME/xkb/symbols/other

// map first key in bottom row (Z in the US layout) to k/K
partial alphanumeric_keys
xkb_symbols "baz" {
    key <AB01> {        [      k, K ]       };
};

With these in place, a user may select any layout/variant together with the custom:foo and/or custom:baz options.

Remarks: This example uses file names custom and other that should not clash with the system files in <datadir>/X11/xkb/symbols. Using the same file name than the system files is possible but may require special handling, see: Using system file names.

The previous examples use custom keymap files with file name that do not clash with the files in the system directory, <datadir>/X11/xkb/. It is possible to add a custom variant/option using the same file name than the system file, e.g. $XDG_CONFIG_HOME/xkb/symbols/us instead of $XDG_CONFIG_HOME/xkb/symbols/banana for the example in Adding a layout.

Compatibility

Attention: For libxkbcommon < 1.9, the custom file must contain an explicit default section if the system file has one, else it may break the keyboard setup by including a section of the custom file instead of the system one. The custom default section should enforce that the system default section is included.
The following example defines a broccoli layout variant:
Content of $XDG_CONFIG_HOME/xkb/symbols/us

// Explicit default section with no name required

default partial alphanumeric_keys

xkb_symbols { include "us(basic)" };

partial alphanumeric_keys

xkb_symbols "broccoli" {

include "us(basic)"

name[Group1] = "Broccoli";

key <AD05> { [ b, B, U1F966 ]}; // 🥦

include "level3(ralt_switch)"

};

For libxkbcommon ≥ 1.9 an explicit default section is not required anymore: libxkbcommon will look up for the proper default section in the XKB paths:
Content of $XDG_CONFIG_HOME/xkb/symbols/us

// No default section required

partial alphanumeric_keys

xkb_symbols "broccoli" {

include "us(basic)"

name[Group1] = "Broccoli";

key <AD05> { [ b, B, U1F966 ]}; // 🥦

include "level3(ralt_switch)"

};

Overriding the system sections

One may override the system sections:

Simply use the same section name.
For the default section, additionally prepend the flag default before xkb_symbols in the custom file.

Warning: It will affect all layouts/variants that depend on the system section.; Including the system section can lead to a circular import.

Therefore is it highly recommended to not override the system sections and prefer creating proper independent variants.

Since: 1.11.0: It is possible to include the system section and avoid circular include by prepending %S to the included file. See the corresponding documentation.

Warning: The below requires libxkbregistry as XKB lookup tool and does not work where clients parse the XML file directly.

The above sections apply only to the data files and require that the user knows about the existence of the new entries. To make custom entries discoverable by the configuration tools (e.g. the GNOME Control Center), the new entries must also be added to the XML file that is parsed by libxkbregistry. In most cases, this is the evdev.xml file in the rules directory.

The following tags are required:

name

For layouts, this is the name of the corresponding file.
For variant, this is the name of the corresponding section in the file.
For options, this is the unique identifier used in the rules file (see Adding an option), usually following the pattern <group>:<option_name>.

shortDescription

For layout and variants, this is the ISO 639 language code.

description

This is the text that will be displayed to label the entry. For layouts and variants, this should be the same as name[Group1].

See the xkeyboard-config documentation for further information.

The example below shows the XML file that would add the custom layout and custom options as outlined above to the XKB registry:

Content of $XDG_CONFIG_HOME/xkb/rules/evdev.xml

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE xkbConfigRegistry SYSTEM "xkb.dtd">
 <xkbConfigRegistry version="1.1">
   <layoutList>
     
     <layout>
       
       <configItem>
         
         <name>banana</name>
         <shortDescription>ban</shortDescription>
         
         <description>Banana (US)</description>
       </configItem>
       
       <variantList>
         <variant>
           <configItem>
             
             <name>orange</name>
             <shortDescription>or</shortDescription>
             
             <description>Banana (Eurosign on 5)</description>
           </configItem>
         </variant>
       </variantList>
     </layout>
     
     <layout>
       <configItem>
         
         <name>us</name>
       </configItem>
       <variantList>
         <variant>
           <configItem>
             
             <name>broccoli</name>
             <shortDescription>bro</shortDescription>
             
             <description>Broccoli</description>
           </configItem>
         </variant>
       </variantList>
     </layout>
   </layoutList>
   <optionList>
     <group allowMultipleSelection="true">
       <configItem>
         <name>custom</name>
         <description>Custom options</description>
       </configItem>
       <option>
       <configItem>
         <name>custom:foo</name>
         <description>Map Tilde to nothing</description>
       </configItem>
       </option>
       <option>
       <configItem>
         <name>custom:baz</name>
         <description>Map Z to K</description>
       </configItem>
       </option>
     </group>
   </optionList>
 </xkbConfigRegistry>

The default behavior of libxkbregistry ensures that the new layout and options are added to the system-provided layouts and options.

For details on the XML format, see the DTD in <datadir>/X11/xkb/rules/xkb.dtd and the system-provided XML files <datadir>/X11/xkb/rules/*.xml.

Note: Depending on the desktop environment, it may require restarting the session in order to make the configuration changes effective.; It is advised to try the custom configuration before restarting the session using the various xkbcli tools. See debugging for further details.

Table of Contents

RMLVO vs KcCGST

Compatibility

Overriding the system sections