Keyboard layout switching

From Gentoo Wiki
Jump to: navigation, search

Keyboard layout maps scancodes from a keyboard into characters sent to application. Keyboard layout can also do more complex transformations via so called dead keys which do not output characters on their own but modify output of subsequent keys. An appropriate keyboard layout is required to support both non-QWERTY keyboards as well as QWERTY keyboards used to enter characters outside of ASCII set.



Edit /etc/conf.d/keymaps which is documented but not very understandable. It appears that one should choose appropriate keyboard map likely from /usr/share/keymaps/i386/qwerty/ as the value for keymap and then optionally also pick files from appropriate include directory such as /usr/share/keymaps/i386/include/ other locations might or might not work as values for the extended_keymaps variable.

FILE /etc/conf.d/keymapsExample configuration

Lastly add /etc/init.d/keymaps to the boot run level.

root #rc-update add keymaps boot
It might be necessary to also edit /etc/conf.d/consolefont to have tty show non-ASCII characters.

Custom Keymap

To make your own keymap just look at the provided keymaps in /usr/share/keymaps for examples.

user $vi <your map>.map
user $gzip <your map>.map
root #mv <your map>.map /usr/share/keymaps/<some directory>

Here is an example custom keymap which is the same as the U.S. qwerty keymap except the forward slash and apostrophe keys are swapped:

FILE /usr/share/keymaps/i386/qwerty/ Keymap
include ""
keycode  40 = slash            question
keycode  53 = apostrophe       quotedbl
Your personal keycodes likely differ.

To find the keycodes mapped to keys you can view the output of:

user $dumpkeys -l

or if you can't find your key run:

user $showkey

Just press the key and its keycode will be shown. When you're done wait a few seconds, and showkey will close.


systemd uses /etc/vconsole.conf and includes both tty font and keyboard layout settings but lacks advanced settings found in OpenRC. Valid values should match what OpenRC supports for the corresponding variable.

FILE /etc/vconsole.confExample settings


Modern X11 applications usually use libXklavier (das Klavier being German for keyboard so it has nothing to do with a certain K DE) and can be configured by using setxkbmap. Furthermore X11 supports much broader set of keyboard layouts than virtual terminal. It should be kept in mind that proper desktop environment will do its own keyboard layout management and there's no need to directly use aforementioned application but it can come in handy when dealing with broken or lacking keyboard layout management.


Open System Settings and navigate to Input Devices module.

Generic desktop environment

Edit ~/.xprofile and call setxkbmap from there.

Recent versions of GNOME 3 do not use libXklavier anymore therefore this might not work at all or likely get overriden by GNOME. Similarly any other desktop environment might also override libXklavier configuration as part of initialization or layout change.
~/.xprofile is a non-standard file that's sourced only when logging in via display manager that supports it (possibly only GDM, KDM and LXDM) and it might be distribution specific although all common distributions seem to support this file.

lxpanel's Keyboard Layout Handler

lxde-base/lxpanel provides a keyboard layout handler as panel item. Lxpanel kyboard layout handler.png

Generic X11

Querying existing configuration:

user $setxkbmap -query

Setting a keyboard layout:

user $setxkbmap lv

Setting a keyboard layout and its variant:

user $setxkbmap lv apostrophe

Finding the supported layouts and variants or values of other xkb properties does not appear to be possible with this application and the only generic way to determine supported values is by examining /usr/share/X11/xkb/. For sake of sanity use of a proper desktop environment with its own keyboard layout management is advised.

Editing 10-keyboard.conf file

This method is recommended for configuration without desktop environments, in other words just X11 with a window manager. Create the 10-keyboard.conf file and configure it with relative keyboard settings.

FILE /etc/X11/xorg.conf.d/10-keyboard.confExample for brazilian keyboard
Section "InputClass"
   Identifier "keyboard-all"
   Driver "evdev"
   Option "XkbLayout" "br"
   Option "XkbVariant" "abnt2"
   MatchIsKeyboard "on"