---
name: "setxkbmap"
section: "1x"
platform: "linux"
package: "xbase-clients"
version: "4.3.0.dfsg.1-14sarge7"
release: "Debian 3.1 (Sarge)"
platforms: ["linux"]
url: "https://new.carta.tech/setxkbmap/1x"
---

# setxkbmap(1x)

configure the keyboard using the X Keyboard Extension

## NAME

setxkbmap - configure the keyboard using the X Keyboard Extension

## SYNOPSIS

**setxkbmap** \[*option* ...\] \[*layout* \[*variant* \[*xkboption* ...\] \] \]

## DESCRIPTION

The **setxkbmap** command configures the keyboard to use the layout determined by the parameters specified on the command line. An XKB keymap is constructed from a number of components which are compiled only as needed. The source for all of the components can be found in */usr/X11R6/lib/X11/xkb*.

If one or more non-option arguments are provided, the first is interpreted as a layout.

If two or more non-option arguments are provided, the second is interpreted as the variant.

If three or more non-option arguments are provided, the third and subsequent ones are interpreted as XKB options.

## OPTIONS

- **-?**, **-help**

  Print a usage message and exit.

- **-compat** *name*

  Use the specified compatibility map component to construct a keyboard layout.

- **-config** *file*

  Use the specified XKB configuration file, which describes the keyboard to be used.

- **-display** *display*

  Update the specified display with the new keyboard layout.

- **-geometry** *name*

  Use the specified geometry component to construct a keyboard layout.

- **-keymap** *name*

  Use the specified keymap description to construct a keyboard layout.

- **-layout** *name*

  Use the specified layout to determine the components which make up the keyboard description. Only one layout is permitted.

- **-model** *name*

  Use the specified keyboard model to determine the components which make up the keyboard description. Only one model is permitted.

- **-option** *name*

  Use the specified option to determine the components which make up the keyboard description; multiple options may be specified, one per **-option** flag. Note that **setxkbmap** does not replace, but merely adds to, any XKB options already set on the display (these are saved in root window properties). If you want *only* the specified options to be set, use the **-option** flag with an empty argument first.

- **-print**

  Print component names in a format acceptable by [**xkbcomp**(1x)](/xkbcomp/1x.md) (an XKB keymap compiler) and exit. This option is useful for testing, or when one needs to run both **setxkbmap** and **xkbcomp** in a pipeline (see below).

- **-rules** *file*

  Use the specified rules file to resolve the requested layout and model to a set of component names. Only one rules file is permitted.

- **-symbols** *name*

  Use the specified symbols component to construct a keyboard layout.

- **-synch**

  Force synchronization of X requests.

- **-types** *name*

  Use the specified types component to construct a keyboard layout.

- **-variant** *name*

  Use the specified layout variant to determine which components will make up the keyboard description. Only one variant is permitted.

- **-v** *level,* **-verbose** *level*

  Set verbosity to specified level.

## USING WITH xkbcomp

If an X server and X client are running on different computers and the XKB configuration files on those machines differ, problems may result when specifying a keyboard map. This is because **setxkbmap** converts the XKB component names to the names of XKB configuration files according to the XKB data on the client machine. It then sends the file names to the X server, where **xkbcomp** composes a complete keyboard map using *its* XKB configuration files. Thus, if the sets of files differ significantly, the names that **setxkbmap** generates on the client side may be unacceptable on the server side, or cause unexpected keyboard behavior. One way to solve this problem is by running **xkbcomp** on the client side as well. Use the **-print** option of **setxkbmap** to print the XKB description in an appropriate format to standard output, and connect that to **xkbcomp**'s standard input with a pipe. For example, the command

```
setxkbmap -print us | xkbcomp - $DISPLAY
```

generates both the XKB keyboard description (**setxkbmap**) and the compiled XKB keyboard map (**xkbcomp**) on the client side, and then uploads the map to the X server at *$DISPLAY*.

## FILES

*/usr/X11R6/lib/X11/xkb*

## SEE ALSO

[**X**(7x)](/X/7x.md), [**xkbbell**(1x)](/xkbbell/1x.md), [**xkbcomp**(1x)](/xkbcomp/1x.md), [**xkbevd**(1x)](/xkbevd/1x.md), [**xkbprint**(1x)](/xkbprint/1x.md), [**xkbvleds**(1x)](/xkbvleds/1x.md), [**xkbwatch**(1x)](/xkbwatch/1x.md)

## COPYRIGHT

Copyright 1994, Silicon Graphics Computer Systems and X Consortium, Inc.\
 See [**X**(7x)](/X/7x.md) for a full statement of rights and permissions.

## AUTHOR

Erik Fortune, Silicon Graphics