---
name: "setxkbmap"
section: "1"
platform: "linux"
package: "xorg-setxkbmap"
version: "1.3.5-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/setxkbmap"
---

# setxkbmap(1)

set keymaps and layouts via the X Keyboard Extension

## 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)](/X/7.md) session. For a table of available layouts and options, see [xkeyboard-config(7)](/xkeyboard-config/7.md).

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)](/Xorg/1.md) 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)](/xkbcomp/1.md) 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)](/xkbcomp/1.md) 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)](/X/7.md) client. Those filenames are then passed to the [Xorg(1)](/Xorg/1.md) server, unless printed to [stdout(4)](/stdout/4.md), 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)](/Xserver/1.md) 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)](/X/7.md) session. Start [X(7)](/X/7.md) 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)](/Xwayland/1.md) session. Use the Wayland Compositor's native XKB configuration method instead.

## SEE ALSO

[xkbcomp(1)](/xkbcomp/1.md), [X(7)](/X/7.md), [xkeyboard-config(7)](/xkeyboard-config/7.md)

## HISTORY

**setxkbmap** first appeared in XFree86 3.2.