setxkbmap

Set the keyboard in French AZERTY

$ setxkbmap [fr]

$ setxkbmap -layout [us,de] -variant [,qwerty] -option ['grp:alt_caps_toggle']

$ localectl list-x11-keymap-layouts

$ localectl list-x11-keymap-variants [de]

$ localectl list-x11-keymap-options | grep grp:

$ setxkbmap -help

setxkbmap [options] [layout [variant [option ...]]]

layout
    Specifies the primary keyboard layout to use (e.g., 'us', 'de', 'fr'). This is a common positional argument.

variant
    Specifies a variant for the chosen layout (e.g., 'dvorak' for the 'us' layout, 'neo' for 'de'). This is a common positional argument, following the layout.

option
    Specifies one or more keyboard options. Options control various behaviors like layout switching combinations (e.g., 'grp:alt_shift_toggle'), Caps Lock behavior (e.g., 'caps:swapescape'), or compose key settings. Can be repeated or provided as positional arguments after layout/variant.

-rules rules
    Specifies the base rules file to use, defining the available models, layouts, and options. Defaults to 'evdev' on most modern systems.

-model model
    Specifies the keyboard model, which maps physical keycodes to symbolic key names (e.g., 'pc105', 'microsoftpro').

-layout layout
    Explicitly sets the base keyboard layout, equivalent to the positional layout argument.

-variant variant
    Explicitly sets the layout variant, equivalent to the positional variant argument.

-option option
    Explicitly adds a keyboard option. This option can be specified multiple times for multiple options, or options can be space-separated after other positional arguments.

-print
    Prints the XKB configuration it would apply, without actually loading it into the server.

-query
    Queries and prints the currently active XKB configuration on the X server.

-device id
    Applies the configuration to a specific keyboard device identified by its ID. Useful in multi-keyboard setups.

-display display
    Specifies the X server display to connect to (e.g., ':0').

setxkbmap is a utility program used to load a new keyboard description into the X server. It is the standard tool for dynamically changing keyboard layouts, models, and options within the X Window System without needing to restart the X server. Instead of modifying server configuration files directly, setxkbmap interacts with the X Keyboard Extension (XKB) to apply immediate changes. Users can specify a keyboard layout (e.g., 'us', 'fr', 'de'), a keyboard model (e.g., 'pc105'), and various options (e.g., 'grp:alt_shift_toggle' for layout switching or 'caps:swapescape' to remap Caps Lock to Escape). It retrieves keyboard configuration data from a hierarchical collection of XKB data files, which define keyboard rules, layouts, models, and symbols. This allows for flexible and powerful configuration of national layouts, special keybindings, and other keyboard behaviors.

Changes made with setxkbmap are typically transient and apply only to the current X session. They will not persist across reboots unless configured via a startup script (like ~/.xinitrc or ~/.xprofile), a desktop environment's settings, or a system-wide tool like localectl.

Using setxkbmap can sometimes interfere with keyboard settings managed by a desktop environment (e.g., GNOME, KDE), potentially leading to conflicting configurations if both try to control the keyboard.

This command only affects the X Window System; it does not change keyboard settings for virtual consoles (TTYs).

setxkbmap relies on a comprehensive set of XKB configuration files, typically located under /usr/share/X11/xkb/. This directory contains subdirectories like rules/, symbols/, layouts/, geometry/, and compat/, which collectively define all aspects of keyboard behavior, from keycodes and symbols to layouts and options.

Setting a specific layout: setxkbmap us
Setting a layout with a variant: setxkbmap us dvorak
Adding an option for layout switching: setxkbmap us -option grp:alt_shift_toggle
Combining multiple settings: setxkbmap de neo -option caps:swapescape -option grp:win_space_toggle
Querying current settings: setxkbmap -query

setxkbmap is a key component of the X Keyboard Extension (XKB), which was introduced to the X Window System in the early 1990s. XKB revolutionized keyboard configuration by providing a vastly more flexible and powerful system compared to its predecessor, xmodmap. Its design allowed for complex national layouts, multiple symbol groups, and a wide array of customizable options, quickly becoming the standard for X server keyboard management. setxkbmap serves as a high-level front-end to XKB's sophisticated capabilities, abstracting the complexities of directly compiling XKB keymaps with xkbcomp. Its role has remained central in providing dynamic keyboard configuration for graphical Linux and Unix environments.

xkbcomp(1), xmodmap(1), localectl(1), dumpkeys(1), loadkeys(1)