Configure X Keyboard Layouts with setxkbmap

Your keyboard is stuck in the wrong layout mid-session, and setxkbmap fixes that for X11 without touching your desktop settings. You will set and verify a layout, replace rather than accidentally accumulate options, and recover from a test change. The examples use setxkbmap 1.3.4 from Debian package x11-xkb-utils version 7.7+8build2.

• Time: about ten minutes.
• You need: an X11 display and a shell. The commands normally run as your ordinary user.
• Scope: this guide changes the keyboard map for the selected X server, but does not edit a permanent desktop configuration.
• Wayland: stop at the compatibility check. Xwayland does not support changing its keymap with setxkbmap.

1. Check the installed command and display

Confirm which executable and version you are about to use:

$ command -v setxkbmap
/usr/bin/setxkbmap
$ setxkbmap -version
setxkbmap 1.3.4
$ dpkg-query -W -f='${Package} ${Version}\n' x11-xkb-utils
x11-xkb-utils 7.7+8build2

The command talks to an X server, so check the display variable before diagnosing a keyboard problem as an XKB problem:

$ printf 'DISPLAY=%s\n' "${DISPLAY:-<unset>}"
DISPLAY=:0

Your display value will differ. If DISPLAY is unset, or the command later reports it cannot open the display, run it from the graphical session that owns the X server. Do not add sudo as a first response: root may still have the wrong display authorisation.

2. Inspect the current map before changing it

-query prints the current rules, model, layout, variant and options, then exits without changing them:

$ setxkbmap -query
rules:      evdev
model:      pc105
layout:     gb
variant:
options:    

The values are host-specific: the output may name a different rules file, model, layout, variant or options. Save it in your terminal notes if you may need to restore the previous state. A non-zero exit status with an error about opening the display means the inspection did not happen.

3. Apply one layout for a practical test

Pass a layout name directly for a simple change. This example selects the US layout:

$ setxkbmap us
$ setxkbmap -query
rules:      evdev
model:      pc105
layout:     us
variant:
options:

The map changes immediately for clients using that X server. The command does not ask for elevated privileges. Test a few keys before continuing, and if the result is wrong, restore the layout your earlier query reported, for example:

$ setxkbmap gb

This is a session change, not a permanent system change. A desktop environment, display manager or startup script may apply another map later. Do not edit files under /usr/share/X11/xkb to make this test persistent.

4. Set model, variant and more than one layout

Use the long options when you need to make the request clear. The layout list is comma-separated, and variants are matched to layouts in the same order:

$ setxkbmap -model pc105 -layout us,gb -variant ,intl
$ setxkbmap -query
rules:      evdev
model:      pc105
layout:     us,gb
variant:    ,intl
options:

Here the first layout has no variant and the second uses intl. A comma is significant. Do not write a single variant and assume it will describe every layout in a list: check the resulting query rather than trusting a remembered desktop setting.

5. Replace old options explicitly

Options are the easiest part to misread. The manual says options supplied on the command line are added to options already saved in the X root window properties, which means a command can retain an old option unless you clear it first.

To replace the existing option set with one known option, give -option an empty argument before adding the new one:

$ setxkbmap -option '' -option 'caps:escape'
$ setxkbmap -query
rules:      evdev
model:      pc105
layout:     us
variant:
options:    caps:escape

The empty argument is quoted so the shell passes an actual empty value. Without it, caps:escape can be added to an existing set such as grp:alt_shift_toggle. To remove all options, use the empty option alone:

$ setxkbmap -option ''

That second command changes state but is reversible: rerun your intended layout and option command, or restore the values setxkbmap -query recorded.

6. Generate a map without loading it

Use -print when you need to inspect the component names or feed the generated description to xkbcomp. It prints a complete XKB description and exits:

$ setxkbmap -print us
xkb_keymap {
    xkb_keycodes  { include "evdev+aliases(qwerty)" };
    ...
};

The exact component lines depend on the installed XKB data. Do not treat an ellipsis as literal input. The documented cross-machine pattern is:

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

This is useful when the client and X server have different XKB files, because both conversion and compilation happen on the client side. It still changes the keyboard map on the target display, so verify the display value before running the pipeline.

7. Diagnose failures without making them worse

Use -help to confirm option spelling and -v with a level from 0 to 10 for more diagnostic output. The installed command reports levels 1 to 10 in its help, while the manual documents 0 to 10; treat the manual's version-specific behaviour as the reference for scripts and test the exact installed binary.

$ setxkbmap -help
Usage: setxkbmap [options] [<layout> [<variant> [<option> ...]]]
$ setxkbmap -v 10 -query
...

• If -query fails, check DISPLAY, X authorisation and whether the session is X11.
• If a layout or option is rejected, verify its name against the XKB data installed under /usr/share/X11/xkb and rerun with a smaller command.
• Do not overwrite system XKB files or restart a graphical session while investigating a typo.