.Dd March 29, 2025
.Dt SETXKBMAP 1
.Os
.Sh NAME
.Nm setxkbmap
.Nd set keymaps and layouts via the X Keyboard Extension
.Sh SYNOPSIS
.Nm
.Op Ar options
.Op Ar layout Op Ar variant Op Ar option Ar ...
.Sh DESCRIPTION
The
.Nm
utility maps the keyboard to use the specified layout in an
.Xr X 7
session.
For a table of available layouts and options, see
.Xr xkeyboard-config 7 .
.Pp
The options are as follows:
.Bl -tag -width indent
.It Fl ? , Fl help
Print a message describing the valid input to
.Nm .
.It Fl compat Ar name
Specify the name of the compatibility map component
used to construct a keyboard layout.
.It Fl config Ar file
Specify the name of an XKB configuration file
which describes the keyboard to be used.
.It Fl device Ar 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
.Xr Xorg 1
server is updated.
.It Fl display Ar display
Specify the display to be updated with the new keyboard layout.
.It Fl geometry Ar name
Specify the name of the geometry component
used to construct a keyboard layout.
.It Fl I Ar directory
Add a directory to the list of directories to be used
to search for the specified layout or rules files.
.It Fl keycodes Ar name
Specify the name of the keycodes component
used to construct a keyboard layout.
.It Fl keymap Ar name
Specify the name of the keymap description
used to construct a keyboard layout.
.It Fl layout Ar name
Specify the name of the layout used to determine
the components which make up the keyboard description.
The
.Fl layout
option may only be used once.
Multiple layouts can be specified as a comma-separated list.
.It Fl model Ar 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.
.It Fl option Ar name
Specify the name of an option to determine the components
which make up the keyboard description;
multiple options may be specified, one per
.Fl option
flag.
Note that
.Nm
adds options specified in the command line
to the options that were set before
.Pq as saved in root window properties .
If you want to replace all previously specified options,
use the
.Fl option
flag with an empty argument first.
.It Fl print
Print component names in a format acceptable by the
.Xr 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
.Nm
and
.Xr xkbcomp 1
utilities in chain
.Pq see below .
.It Fl query
Print the current rules, model, layout, variant, and options,
then exit.
.It Fl rules Ar file
Specify the name of the rules file used to resolve the requested
layout and model to a set of component names.
.It Fl symbols Ar name
Specify the name of the symbols component
used to construct a keyboard layout.
.It Fl synch
Force synchronization for X requests.
.It Fl types Ar name
Specify the name of the types component
used to construct a keyboard layout.
.It Fl variant Ar name
Specify which variant of the keyboard layout should be used to
determine the components which make up the keyboard description.
The
.Fl 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
.Fl layout .
.It Fl v Ns Oo Sy erbose Oc Op Ar level
Specify level of verbosity in output messages.
Valid levels range from 0
.Pq least verbose
to 10
.Pq most verbose .
Default: 5.
If no level is specified, each
.Fl v
or
.Fl verbose
flag raises the level by 1.
.It Fl version
Print the utility's version number and exit.
.El
.Sh 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
.Pa __xkbconfigroot__
on the
.Xr X 7
client.
Those filenames are then passed to the
.Xr Xorg 1
server, unless printed to
.Xr stdout 4 ,
with
.Fl print .
.Sh FILES
.Bl -tag -width __xkbconfigroot__
.It Pa __xkbconfigroot__
source for all XKB components
.El
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
Rebind the Caps Lock key as an additional Left Control:
.Pp
.Dl setxkbmap -option ctrl:nocaps
.Pp
Set the layout to US, composing the keymap on the client for situations
where XKB component files may differ between the
.Xr Xserver 1
and client:
.Pp
.Dl setxkbmap us -print | xkbcomp - $DISPLAY
.Pp
Reset XKB options:
.Pp
.Dl setxkbmap -option
.Sh DIAGNOSTICS
.Bl -diag
.It Cannot open display \&"default display\&"
The shell environment is not aware of a currently running
.Xr X 7
session.
Start
.Xr X 7
before using this utility, or set the
.Ev DISPLAY
environment variable.
.It Running setxkbmap against an Xwayland server
This utility will not run in an
.Xr Xwayland 1
session.
Use the Wayland Compositor's native XKB configuration method instead.
.El
.Sh SEE ALSO
.Xr xkbcomp 1 ,
.Xr X 7 ,
.Xr xkeyboard-config 7
.Sh HISTORY
.Nm
first appeared in XFree86 3.2.