SETXKBMAP(1) | General Commands Manual | 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/X11R7/lib/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/X11R7/lib/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.

March 29, 2025 | NetBSD 11.99