NAME

setxkbmap — set keymaps and layouts via the X Keyboard Extension

SYNOPSIS

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

The setxkbmap utility exits 0 on success, and >0 if an error occurs.

EXAMPLES

Rebind the Caps Lock key as an additional Left Control:

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:

Reset XKB options:

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.