SETXKBMAP(1)

NAME
setxkbmap - set keymaps and layouts via the X Keyboard Extension

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

DESCRIPTION
The setxkbmap utility maps the keyboard to use the specified layout in an X(7) session. For a table of available layouts and options, see xkeyboard-config(7).

The options are as follows:

?, -help
    Print a message describing the valid input to setxkbmap.

-compat name
    Specify the name of the compatibility map component used to construct a keyboard layout.

-config file
    Specify the name of an XKB configuration file which describes the keyboard to be used.

-device deviceid
    Specify the numeric device id of the input device to be updated with the new keyboard layout. If not specified, the core keyboard device of the Xorg(1) server is updated.

-display display
    Specify the display to be updated with the new keyboard layout.

-geometry name
    Specify the name of the geometry component used to construct a keyboard layout.

-I directory
    Add a directory to the list of directories to be used to search for the specified layout or rules files.

-keycodes name
    Specify the name of the keycodes component used to construct a keyboard layout.

-keymap name
    Specify the name of the keymap description used to construct a keyboard layout.

-layout name
    Specify the name of the layout used to determine the components which make up the keyboard description. The -layout option may only be used once. Multiple layouts can be specified as a comma-separated list.

-model name
    Specify the name of the keyboard model used to determine the components which make up the keyboard description. Only one model may be specified on the command line.

-option name
    Specify the name of an option to determine the components which make up the keyboard description; multiple options may be specified, one per -option flag. Note that 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.

-print
    Print component names in a format acceptable by the xkbcomp(1) keymap compiler and exit. The option can be used for tests instead of a verbose option and in cases when one needs to run both the setxkbmap and xkbcomp(1) utilities in chain (see below).

-query
    Print the current rules, model, layout, variant, and options, then exit.

-rules file
    Specify the name of the rules file used to resolve the requested layout and model to a set of component names.

-symbols name
    Specify the name of the symbols component used to construct a keyboard layout.

-synch
    Force synchronization for X requests.

-types name
    Specify the name of the types component used to construct a keyboard layout.

-variant name
    Specify which variant of the keyboard layout should be used to determine the components which make up the keyboard description. The -variant option may only be used once. Multiple variants can be specified as a comma-separated list and will be matched with the layouts specified with -layout.

-v[erbose] [level]
    Specify level of verbosity in output messages. Valid levels range from 0 (least verbose) to 10 (most verbose). Default: 5. If no level is specified, each -v or -verbose flag raises the level by 1.

-version
    Print the utility's version number and exit.

IMPLEMENTATION NOTES
An XKB keymap is constructed from a number of components which are compiled only as needed by converting the arguments to the names of XKB configuration files in /usr/share/X11/xkb on the X(7) client. Those filenames are then passed to the Xorg(1) server, unless printed to stdout(4), with -print.

FILES

/usr/share/X11/xkb
    source for all XKB components

EXIT STATUS

EXAMPLES
Rebind the Caps Lock key as an additional Left Control:

    setxkbmap -option ctrl:nocaps

Set the layout to US, composing the keymap on the client for situations where XKB component files may differ between the Xserver(1) and client:

    setxkbmap us -print | xkbcomp - $DISPLAY

Reset XKB options:

    setxkbmap -option

DIAGNOSTICS

Cannot open display "default display" The shell environment is not aware of a currently running X(7) session. Start X(7) before using this utility, or set the DISPLAY environment variable.

Running setxkbmap against an Xwayland server This utility will not run in an Xwayland(1) session. Use the Wayland Compositor's native XKB configuration method instead.

SEE ALSO
xkbcomp(1), X(7), xkeyboard-config(7)

HISTORY
setxkbmap first appeared in XFree86 3.2.