LinuxCommandLibrary

setxkbmap

Configure keyboard layout

TLDR

Set the keyboard in French AZERTY

$ setxkbmap [fr]
copy

Set multiple keyboard layouts, their variants and switching option
$ setxkbmap -layout [us,de] -variant [,qwerty] -option ['grp:alt_caps_toggle']
copy

Get help
$ setxkbmap -help
copy

List all layouts
$ localectl list-x11-keymap-layouts
copy

List variants for the layout
$ localectl list-x11-keymap-variants [de]
copy

List available switching options
$ localectl list-x11-keymap-options | grep grp:
copy

SYNOPSIS

setxkbmap [options] [layout [variant [options]]]

PARAMETERS

-display
    Specifies the X display to connect to.

-geometry
    Specifies the geometry to use for the keyboard.

-model
    Specifies the keyboard model.

-layout
    Specifies the keyboard layout to use. For example: 'us', 'de', 'fr'.

-variant
    Specifies the keyboard layout variant. For example: 'dvorak' (for us layout), 'nodeadkeys'.

-option
    Specifies a keyboard option. Multiple options can be specified separated by commas. Examples: 'grp:caps_toggle', 'compose:menu'.

-query
    Queries the current keyboard settings.

-print
    Prints the current keyboard settings in a parsable format.

-symbols
    Specifies the keyboard symbols file.

-compat
    Specifies the keyboard compatibility file.

-keycodes
    Specifies the keyboard keycodes file.

-rules
    Specifies the keyboard rules file.

-v
    Verbose output.

DESCRIPTION

The setxkbmap command allows you to configure the keyboard layout settings in the X Window System. It's a crucial tool for customizing your keyboard to match your language, region, or personal preferences. This command interacts with the X Keyboard Extension (XKB), which provides a flexible way to manage keyboard behavior. You can use it to switch between different keyboard layouts, modify key mappings, and enable specific keyboard options.
Using setxkbmap, one can quickly change the active keyboard layout without needing to restart the X server or log out. Common use cases include switching between different language layouts (e.g., English, French, German), enabling special keyboard features, or troubleshooting keyboard issues related to layout configuration. Configuration can be done via command line or setup in a shell to be executed on login. Be aware that the configuration will be lost after a reboot, unless it is set up to be run automatically on login.

CAVEATS

Changes made with setxkbmap are typically not persistent across reboots. To make the changes permanent, you need to configure your desktop environment or use a startup script.

PERSISTENCE

To make keyboard layout changes persistent, you'll generally need to configure your desktop environment's keyboard settings. The specific method depends on your distribution and desktop environment (e.g., GNOME, KDE, Xfce). Most environments provide a graphical tool for keyboard layout configuration, which will automatically save the settings so they are applied on login. Alternatively, you can add the setxkbmap command to a startup script or your `.xinitrc` file.
For systemd based distributions, you can use systemd-localed to configure keyboard layout on boot. Please note that in this case you might need to reboot.

EXAMPLES

Setting a US Dvorak layout:
setxkbmap us dvorak
Switching between two layouts using Caps Lock:
setxkbmap -layout us,de -option "grp:caps_toggle"
Query current settings:
setxkbmap -query

HISTORY

The setxkbmap command was developed as part of the X Keyboard Extension (XKB) project to provide a more flexible and configurable keyboard management system compared to older methods. It became widely used with the adoption of XKB in modern Linux distributions. The command allows users to customize their keyboard layout based on factors like language, region and user preferences. The implementation is provided by the xkeyboard-config package.

SEE ALSO

xkbcomp(1), xmodmap(1)

Copied to clipboard