SETXKBMAP(1)

okay so bestie, you're looking at setxkbmap(1) from the General Commands Manual, and it's literally the utility that sets keymaps and layouts via the X Keyboard Extension. no cap, this is the glow-up your keyboard deserves. 💅

---

✨ NAME ✨

setxkbmap — set keymaps and layouts via the X Keyboard Extension. periodt.

---

🌸 SYNOPSIS 🌸

setxkbmap [options] [layout [variant [option ...]]]

---

🦋 DESCRIPTION 🦋

okay so 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). it's giving "keyboard, but make it fashion."

the options are as follows (yes, all of them — we're not skipping a single one):

• -?, -help — prints a message describing the valid input to setxkbmap. (a little help menu, we love that for us.)
• -compat name — specifies the name of the compatibility map component used to construct a keyboard layout.
• -config file — specifies the name of an XKB configuration file which describes the keyboard to be used.
• -device deviceid — specifies the numeric device id of the input device to be updated with the new keyboard layout. if you don't specify it, the core keyboard device of the Xorg(1) server gets updated. (that's the default, bestie.)
• -display display — specifies the display to be updated with the new keyboard layout.
• -geometry name — specifies the name of the geometry component used to construct a keyboard layout.
• -I directory — adds a directory to the list of directories to be used to search for the specified layout or rules files. (stack those search paths, bestie.)
• -keycodes name — specifies the name of the keycodes component used to construct a keyboard layout.
• -keymap name — specifies the name of the keymap description used to construct a keyboard layout.
• -layout name — specifies 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 — specifies 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 — specifies 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. (this is the messy part, so read it twice, bestie.)
• -print — prints component names in a format acceptable by the xkbcomp(1) keymap compiler and exits. 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 — prints the current rules, model, layout, variant, and options, then exits.
• -rules file — specifies the name of the rules file used to resolve the requested layout and model to a set of component names.
• -symbols name — specifies the name of the symbols component used to construct a keyboard layout.
• -synch — forces synchronization for X requests.
• -types name — specifies the name of the types component used to construct a keyboard layout.
• -variant name — specifies 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] — specifies 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 — prints the utility's version number and exits.

---

🧚 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) client. those filenames are then passed to the Xorg(1) server, unless printed to stdout(4), with -print. (the way that it compiles only as needed? highkey efficient.)

---

🎀 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. periodt.

---

💖 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. (basically, your shell is lost in the sauce.)
• 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. (not me trying to run this in Xwayland — it's not happening, bestie.)

---

🌈 SEE ALSO 🌈

go check out xkbcomp(1), X(7), and xkeyboard-config(7) — iykyk.

---

👑 HISTORY 👑

setxkbmap first appeared in XFree86 3.2. (a legend was born.)

---

this iconic page is from Debian, dated March 29, 2025, and yes it's still SETXKBMAP(1) — bye bestie, mwah 💋✨