SETXKBMAP(1) User Commands SETXKBMAP(1)
setxkbmap - set keymaps and layouts via the X Keyboard Extension
setxkbmap [options] [layout [variant [option ...]]]
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.
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.
/usr/share/X11/xkb source for all XKB components
The setxkbmap utility exits 0 on success, and >0 if an error occurs.
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
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.
xkbcomp(1), X(7), xkeyboard-config(7)
setxkbmap first appeared in XFree86 3.2.
illumos March 29, 2025 illumos
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
The setxkbmap utility exits 0 on success, and >0 if an error occurs.
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.
illumos March 29, 2025 illumos