Difference between revisions of "Keyboard configuration in Xorg"

From ArchWiki
Jump to: navigation, search
(Using setxkbmap: added quotes around -layout argument. Quotes are needed in case the layout name contains brackets.)
(move link to #See also section (still seems more suitable for X KeyBoard extension than this page...))
 
(114 intermediate revisions by 32 users not shown)
Line 1: Line 1:
 
[[Category:Keyboards]]
 
[[Category:Keyboards]]
[[Category:X Server]]
+
[[Category:X server]]
[[es:Keyboard Configuration in Xorg]]
+
[[es:Keyboard configuration in Xorg]]
[[ja:Keyboard Configuration in Xorg]]
+
[[ja:Xorg でのキーボード設定]]
{{Article summary start}}
+
{{Related articles start}}
{{Article summary text|Basic configuration of keyboard layouts in [[Xorg]].}}
+
{{Related|Keyboard configuration in console}}
{{Article summary heading|Related}}
+
{{Related|Extra keyboard keys}}
{{Article summary wiki|Keyboard Configuration in Console}}
+
{{Related|Xorg}}
{{Article summary wiki|Extra Keyboard Keys}}
+
{{Related|X KeyBoard extension}}
{{Article summary wiki|Xorg}}
+
{{Related articles end}}
{{Article summary wiki|X KeyBoard extension}}
+
{{Article summary heading|DE-specific configuration}}
+
{{Article summary wiki|GNOME#Modify Keyboard with XkbOptions}}
+
{{Article summary wiki|KDE#Set keyboard}}
+
{{Article summary end}}
+
  
{{Note|This article covers only basic configuration without modifying layouts, mapping extra keys etc. See [[Extra Keyboard Keys]] for these advanced topics.}}
+
This article's purpose is to detail basic Xorg server keyboard configuration. For advanced topics such as keyboard layout modification or additional key mappings, see [[X KeyBoard extension]] or [[Extra keyboard keys]] respectively.
  
Xorg uses the [[X KeyBoard extension]] (XKB) to manage keyboard layouts. Alternatively, [[xmodmap]] can be used to access the internal keymap table directly. Generally it is not recommended to use ''xmodmap'', except perhaps for the simplest tasks.
+
== Overview ==
  
This article describes low-level configuration using XKB which is effective in most cases, but some desktop environments like [[GNOME]] override it with its own settings.
+
The Xorg server uses the [[X KeyBoard extension]] (XKB) to define keyboard layouts. Optionally, [[xmodmap]] can be used to access the internal keymap table directly, although this is not recommended for complex tasks. Also [[systemd]]'s ''localectl'' can be used to define the keyboard layout for both the Xorg server and the virtual console.
 +
 
 +
{{Note|XKB options can be overridden by the tools provided by some desktop environments such as [[GNOME#XkbOptions_keyboard_options|GNOME (XkbOptions)]] and [[KDE#Set keyboard|KDE (set keyboard)]].}}
  
 
== Viewing keyboard settings ==
 
== Viewing keyboard settings ==
Line 60: Line 57:
  
 
== Setting keyboard layout ==
 
== Setting keyboard layout ==
 +
 +
{{Expansion|Udev also comes into play (for example when plugging in a keyboard), undoing changes by ''setxkbmap''}}
  
 
Keyboard layout in Xorg can be set in multiple ways. Here is an explanation of used options:
 
Keyboard layout in Xorg can be set in multiple ways. Here is an explanation of used options:
Line 65: Line 64:
 
* {{ic|XkbModel}} selects the keyboard model. This has an influence only for some extra keys your keyboard might have. The safe fallback are {{ic|pc104}} or {{ic|pc105}}. But for instance laptops usually have some extra keys, and sometimes you can make them work by simply setting a proper model.
 
* {{ic|XkbModel}} selects the keyboard model. This has an influence only for some extra keys your keyboard might have. The safe fallback are {{ic|pc104}} or {{ic|pc105}}. But for instance laptops usually have some extra keys, and sometimes you can make them work by simply setting a proper model.
 
* {{ic|XkbLayout}} selects the keyboard layout. Multiple layouts may be specified in a comma-separated list, e.g. if you want to quickly switch between layouts.
 
* {{ic|XkbLayout}} selects the keyboard layout. Multiple layouts may be specified in a comma-separated list, e.g. if you want to quickly switch between layouts.
* {{ic|XkbVariant}} selects a specific layout variant. For instance, the default {{ic|sk}} variant is {{ic|qwertz}}, but you can manually specify {{ic|qwerty}} etc.
+
* {{ic|XkbVariant}} selects a specific layout variant. For instance, the default {{ic|sk}} variant is {{ic|qwertz}}, but you can manually specify {{ic|qwerty}}, etc.
: {{Warning|You must specify as many variants as the number of specified layouts. If you want the default variant, specify an empty string as the variant (the comma must stay). For example, to have the default {{ic|us}} layout as primary and the {{ic|dvorak}} variant of {{ic|us}} layout as secondary, specify {{ic|us,us}} as {{ic|XkbLayout}} and {{ic|,dvorak}} as {{ic|XkbVariant}}.}}
+
* {{ic|XkbOptions}} contains some extra options. Used for specifying layout switching, notification LED, compose mode etc. See the [[#Frequently used XKB options]] section for examples.
* {{ic|XkbOptions}} contains some extra options. Used for specifying layout switching, notification LED, compose mode etc.
+
 
 +
{{Note|You must specify as many variants as the number of specified layouts. If you want the default variant, specify an empty string as the variant (the comma must stay). For example, to have the default {{ic|us}} layout as primary and the {{ic|dvorak}} variant of {{ic|us}} layout as secondary, specify {{ic|us,us}} as {{ic|XkbLayout}} and {{ic|,dvorak}} as {{ic|XkbVariant}}.}}
  
 
The layout name is usually a [[Wikipedia:ISO_3166-1_alpha-2#Officially_assigned_code_elements|2-letter country code]]. To see a full list of keyboard models, layouts, variants and options, along with a short description, open {{ic|/usr/share/X11/xkb/rules/base.lst}}. Alternatively, you may use one of the following commands to see a list without a description:
 
The layout name is usually a [[Wikipedia:ISO_3166-1_alpha-2#Officially_assigned_code_elements|2-letter country code]]. To see a full list of keyboard models, layouts, variants and options, along with a short description, open {{ic|/usr/share/X11/xkb/rules/base.lst}}. Alternatively, you may use one of the following commands to see a list without a description:
Line 76: Line 76:
 
* {{ic|localectl list-x11-keymap-options}}
 
* {{ic|localectl list-x11-keymap-options}}
  
Examples in the following subsections will have the same effect, they will set {{ic|pc104}} model, {{ic|cz}} as primary layout, {{ic|us}} as secondary layout, {{ic|dvorak}} variant for {{ic|us}} layout and the {{ic|Alt+Shift}} combination for switching between layouts.
+
Examples in the following subsections will have the same effect, they will set {{ic|pc104}} model, {{ic|cz}} as primary layout, {{ic|us}} as secondary layout, {{ic|dvorak}} variant for {{ic|us}} layout and the {{ic|Alt+Shift}} combination for switching between layouts. See {{ic|man xkeyboard-config}} for more detailed information.
  
 
=== Using setxkbmap ===
 
=== Using setxkbmap ===
  
The tool ''setxkbmap'' sets the keyboard layout for an active X server and the setting is persistent only until the session ends, but you can use [[xinitrc]] to make it persistent across reboots. It is useful to override system-wide configuration specified by [[#Using X configuration files|X configuration files]].
+
''setxkbmap'' sets the keyboard layout for the current X session only, but can be made persistent in [[~/.xinitrc]]. This overrides system-wide configuration specified following [[#Using X configuration files]].
  
The usage is as follows:
+
The usage is as follows (see {{ic|man 1 setxkbmap}}):
  
 
  $ setxkbmap [-model ''xkb_model''] [-layout ''xkb_layout''] [-variant ''xkb_variant''] [-option ''xkb_options'']
 
  $ setxkbmap [-model ''xkb_model''] [-layout ''xkb_layout''] [-variant ''xkb_variant''] [-option ''xkb_options'']
  
It is not necessary to specify all options, e.g. you can change just a layout:
+
To change just the layout ({{ic|-layout}} is the default flag):
  
  $ setxkbmap -layout ''xkb_layout''
+
  $ setxkbmap ''xkb_layout''
  
See {{ic|man 1 setxkbmap}} for a full list of command line arguments.
+
For multiple customizations:
  
For example:
+
$ setxkbmap -model pc104 -layout cz,us -variant ,dvorak -option grp:alt_shift_toggle
  
$ setxkbmap -model pc104 -layout "cz,us" -variant ,dvorak -option grp:alt_shift_toggle
+
=== Using X configuration files ===
  
=== Using X configuration files ===
+
{{Note|{{ic|xorg.conf}} is parsed by the X server at start-up. To apply changes, restart X.}}
  
 
The syntax of X configuration files is explained in [[Xorg#Configuration]]. This method creates system-wide configuration which is persistent across reboots.
 
The syntax of X configuration files is explained in [[Xorg#Configuration]]. This method creates system-wide configuration which is persistent across reboots.
Line 102: Line 102:
 
Here is an example:
 
Here is an example:
  
{{hc|/etc/X11/xorg.conf.d/10-keyboard.conf|
+
{{hc|/etc/X11/xorg.conf.d/00-keyboard.conf|
 
Section "InputClass"
 
Section "InputClass"
 
         Identifier "system-keyboard"
 
         Identifier "system-keyboard"
Line 113: Line 113:
 
}}
 
}}
  
=== Using localectl ===
+
==== Using localectl ====
  
For convenience, the tool ''localectl'' may be used instead of manual editing of X configuration file. It will save the configuration in {{ic|/etc/X11/xorg.conf.d/00-keyboard.conf}}, this file should not be manually edited, because ''localectl'' will overwrite the changes on next start.
+
For convenience, the tool ''localectl'' may be used instead of manually editing X configuration files. It will save the configuration in {{ic|/etc/X11/xorg.conf.d/00-keyboard.conf}}, this file should not be manually edited, because ''localectl'' will overwrite the changes on next start.
  
 
The usage is as follows:
 
The usage is as follows:
  
  $ localectl set-x11-keymap ''layout'' [''model''] [''variant''] [''options'']
+
  $ localectl [--no-convert] set-x11-keymap ''layout'' [''model'' [''variant'' [''options'']]]
  
The following command will create a file {{ic|/etc/X11/xorg.conf.d/00-keyboard.conf}} with pretty much the same content as the example above:
+
To set a ''model'', ''variant'' or ''options'', all preceding fields need to be specified. Unless the {{ic|--no-convert}} option is passed, the specified keymap is also converted to the closest matching console keymap and applied to the [[Keyboard configuration in console|console configuration]] in {{ic|vconsole.conf}}. See {{ic|man localectl}} for more information.
  
  $ localectl set-x11-keymap cz,us pc104 ,dvorak grp:alt_shift_toggle
+
To create a {{ic|/etc/X11/xorg.conf.d/00-keyboard.conf}} like the above:
 +
 
 +
  $ localectl --no-convert set-x11-keymap cz,us pc104 ,dvorak grp:alt_shift_toggle
  
 
== Frequently used XKB options ==
 
== Frequently used XKB options ==
Line 131: Line 133:
 
To be able to easily switch keyboard layouts, first specify multiple layouts between which you want to switch (the first one is the default). Then specify a key (or key combination), which will be used for switching. For example, to switch between a US and a Swedish layout using the {{ic|CapsLock}} key, use {{ic|us,se}} as an argument of {{ic|XkbLayout}} and {{ic|grp:caps_toggle}} as an argument of {{ic|XkbOptions}}.
 
To be able to easily switch keyboard layouts, first specify multiple layouts between which you want to switch (the first one is the default). Then specify a key (or key combination), which will be used for switching. For example, to switch between a US and a Swedish layout using the {{ic|CapsLock}} key, use {{ic|us,se}} as an argument of {{ic|XkbLayout}} and {{ic|grp:caps_toggle}} as an argument of {{ic|XkbOptions}}.
  
You can use other key combinations than {{ic|CapsLock}}, they are listed in {{ic|/usr/share/X11/xkb/rules/base.lst}}, start with {{ic|grp:}} and end with {{ic|_toggle}}. To get the full list of available options, run the following command:
+
You can use other key combinations than {{ic|CapsLock}}, they are listed in {{ic|/usr/share/X11/xkb/rules/base.lst}}, start with {{ic|grp:}} and end with {{ic|toggle}}. To get the full list of available options, run the following command:
  
  $ grep "grp:.*_toggle" /usr/share/X11/xkb/rules/base.lst
+
  $ grep "grp:.*toggle" /usr/share/X11/xkb/rules/base.lst
  
 
=== Terminating Xorg with Ctrl+Alt+Backspace ===
 
=== Terminating Xorg with Ctrl+Alt+Backspace ===
  
By default, the key combination {{ic|Ctrl+Alt+Backspace}} is disabled. You can enable it by passing {{ic|terminate:ctrl_alt_bksp}} to {{ic|XkbOptions}}.
+
By default, the key combination {{ic|Ctrl+Alt+Backspace}} is disabled. You can enable it by passing {{ic|terminate:ctrl_alt_bksp}} to {{ic|XkbOptions}}. This can also be done by binding a key to {{ic|Terminate_Server}} in {{ic|xmodmap}} (which undoes any existing {{ic|XkbOptions}} setting). In order for either method to work, one also needs to have {{ic|DontZap}} set to "off" in {{ic|ServerFlags}}; however, this is now the default.
  
 
=== Swapping Caps Lock with Left Control ===
 
=== Swapping Caps Lock with Left Control ===
Line 151: Line 153:
 
=== Configuring compose key ===
 
=== Configuring compose key ===
  
The [[Wikipedia:Compose key|compose key]], when pressed in sequence with other keys, produces a unicode character. For example, in most configurations pressing {{ic|''compose_key'' ' e}} produces {{ic|é}}. This is especially useful if you need to type in a different language then the one for which the keyboard layout was designed (such as typing in French, Italian and German on an American keyboard).
+
Though typically not on traditional keyboards, a [[Wikipedia:Compose key|Compose key]] can be configured to an existent key.
  
For example, to make the right {{ic|Alt}} key a compose key, pass {{ic|compose:ralt}} to {{ic|XkbOptions}}.
+
The {{ic|Compose}} key begins a keypress sequence that involves (usually two) additional keypresses. Usage is typically either for entering characters in a language that the keyboard was not designed for, or for other less-used characters that are not covered with the {{ic|AltGr}} modifier. For example, pressing {{ic|Compose}} {{ic|'}} {{ic|e}} produces {{ic|é}}, or {{ic|Compose}} {{ic|-}} {{ic|-}} will produce an "em dash": {{ic|—}}.
  
You can use other keys as compose keys, they are listed in {{ic|/usr/share/X11/xkb/rules/base.lst}} and start with {{ic|compose:}}. To get the full list of available options, run the following command:
+
Though a few more eccentric keyboards feature a {{ic|Compose}} key, its availability is usually through substituting an already existing key to it. For example, to make the {{ic|Menu}} key a {{ic|Compose}} key use the [[Desktop environment]] configuration, or pass {{ic|compose:menu}} to {{ic|XkbOptions}} (or [[#Using setxkbmap|setxkbmap]]: {{ic|setxkbmap -option compose:menu}}). Allowed key substitutions are defined in {{ic|/usr/share/X11/xkb/rules/base.lst}}:
  
 
  $ grep "compose:" /usr/share/X11/xkb/rules/base.lst
 
  $ grep "compose:" /usr/share/X11/xkb/rules/base.lst
Line 161: Line 163:
 
==== Key combinations ====
 
==== Key combinations ====
  
The default combinations for the compose keys depend on the locale and are stored in {{ic|/usr/share/X11/locale/''used_locale''/Compose}}, where {{ic|''used_locale''}} is for example {{ic|en_US.UTF-8}}.
+
The default combinations for the compose keys depend on the [[locale]] configured for the session and are stored in {{ic|/usr/share/X11/locale/''used_locale''/Compose}}, where {{ic|''used_locale''}} is for example {{ic|en_US.UTF-8}}.
  
 
You can define your own compose key combinations by copying the default file to {{ic|~/.XCompose}} and editing it. The compose key works with any of the thousands of valid Unicode characters, including those outside the Basic Multilingual Plane.
 
You can define your own compose key combinations by copying the default file to {{ic|~/.XCompose}} and editing it. The compose key works with any of the thousands of valid Unicode characters, including those outside the Basic Multilingual Plane.
Line 168: Line 170:
  
 
{{Tip|XIM is very old, you might have better luck with other input methods: [[Wikipedia:Smart Common Input Method|SCIM]], [[Wikipedia:Uim|uim]], [[Wikipedia:Intelligent Input Bus|IBus]] etc. See [[Internationalization#Input methods in Xorg]] for details.}}
 
{{Tip|XIM is very old, you might have better luck with other input methods: [[Wikipedia:Smart Common Input Method|SCIM]], [[Wikipedia:Uim|uim]], [[Wikipedia:Intelligent Input Bus|IBus]] etc. See [[Internationalization#Input methods in Xorg]] for details.}}
 +
 +
{{Note|XIM will prevent insertion of Unicode characters with the {{ic|Ctrl+Shift+u}} combination.}}
 +
 +
=== Currency sign on other key ===
 +
 +
Most European keyboards have a Euro sign (€) printed on on the {{ic|5}} key. For example, to access it with {{ic|Alt+5}}, use the {{ic|lv3:lalt_switch}} and {{ic|eurosign:5}} options.
 +
 +
The Rupee sign (₹) can be used the same way with {{ic|rupeesign:4}}.
 +
 +
=== Switching state immediately when Caps Lock is pressed ===
 +
 +
Those who prefer typing capital letters with the Caps Lock key may experience a short delay when Caps Lock state is switched, resulting in two or more capital letters (e.g. ''THe'', ''ARch LInux''). This behaviour [[Wikipedia:Caps_lock#History|stems from typewriters]].
 +
 +
Some more popular operating systems have removed this behaviour, either voluntarily (as it can be confusing to some) or by mistake, however this is a question of preference. Bug reports have been filed on the Xserver bug tracker, as there is currently no easy way to switch to the behaviour reflected by those other operating systems. For anyone who would like to follow up the issue, bug reports and latest working progress can be found at [https://bugs.freedesktop.org/show_bug.cgi?id=27903] and [https://bugs.freedesktop.org/show_bug.cgi?id=56491].
 +
 +
==== Workaround ====
 +
 +
First, export your keyboard configurations to a file:
 +
 +
$ xkbcomp -xkb $DISPLAY xkbmap
 +
 +
In the file ''xkbmap'', locate the Caps Lock section which begins with ''key <CAPS>'':
 +
 +
  key <CAPS> {        [      Caps_Lock ] };
 +
 +
and replace whole section with the following code:
 +
 +
key <CAPS> {
 +
    repeat=no,
 +
    type[group1]="ALPHABETIC",
 +
    symbols[group1]=[ Caps_Lock, Caps_Lock],
 +
    actions[group1]=[ LockMods(modifiers=Lock), Private(type=3,data[0]=1,data[1]=3,data[2]=3)]
 +
};
 +
 +
Save and reload keyboard configurations:
 +
 +
$ xkbcomp -w 0 xkbmap $DISPLAY
 +
 +
Consider making it a service launching after X starts, since reloaded configurations do not survive a system reboot.
  
 
== Other settings ==
 
== Other settings ==
Line 173: Line 214:
 
=== Adjusting typematic delay and rate ===
 
=== Adjusting typematic delay and rate ===
  
The ''typematic delay'' indicates the amount of time (typically in miliseconds) a key needs to be pressed in order for the repeating process to begin. After the repeating process has been triggered, the character will be repeated with a certain frequency (usually given in Hz) specified by the ''typematic rate''. These values can be changed using the ''xset'' command:
+
The ''typematic delay'' indicates the amount of time (typically in miliseconds) a key needs to be pressed in order for the repeating process to begin. After the repeating process has been triggered, the character will be repeated with a certain frequency (usually given in Hz) specified by the ''typematic rate''. The typematic delay in the [[Keyboard_configuration_in_console#Adjusting_typematic_delay_and_rate|virtual console]] is not affected by these settings.
 +
 
 +
==== Using xset ====
 +
 
 +
The tool ''xset'' can be used to set the typematic delay and rate for an active X server, certain actions during runtime tho may cause the XServer to reset these changes and revert instead to its ''seat defaults''.
 +
 
 +
Usage:
  
 
  $ xset r rate ''delay'' [''rate'']
 
  $ xset r rate ''delay'' [''rate'']
Line 184: Line 231:
  
 
  $ xset r rate
 
  $ xset r rate
 +
 +
==== Using XServer startup options ====
 +
 +
A more resistant way to set the typematic delay and rate is to make them the ''seat defaults'' by passing the desired settings to the X server on its startup using the following options:
 +
 +
* {{ic|-ardelay ''miliseconds''}} - sets the autorepeat delay (length of time in milliseconds that a key must be depressed before autorepeat starts).
 +
* {{ic|-arinterval ''miliseconds''}} - sets the autorepeat interval (length of time in milliseconds that should elapse between autorepeat-generated keystrokes).
 +
 +
See {{ic|man xserver}} for a full list of X server options and refer to your [[display manager]] for information about how to pass these options.
 +
 +
==== Using XServer options ====
 +
 +
{{Accuracy|1=The AutoRepeat Option has been removed from the keyboad driver version 1.4.0 https://bugzilla.redhat.com/show_bug.cgi?id=601853#c12}}
 +
 +
Add this line to {{ic|/etc/X11/xorg.conf.d/00-keyboard.conf}}:
 +
 +
Option "AutoRepeat" "''delay'' ''rate''"
 +
 +
== See also ==
 +
 +
* [http://madduck.net/docs/extending-xkb/ Madduck guide] on extending XKB

Latest revision as of 09:03, 2 April 2016

This article's purpose is to detail basic Xorg server keyboard configuration. For advanced topics such as keyboard layout modification or additional key mappings, see X KeyBoard extension or Extra keyboard keys respectively.

Overview

The Xorg server uses the X KeyBoard extension (XKB) to define keyboard layouts. Optionally, xmodmap can be used to access the internal keymap table directly, although this is not recommended for complex tasks. Also systemd's localectl can be used to define the keyboard layout for both the Xorg server and the virtual console.

Note: XKB options can be overridden by the tools provided by some desktop environments such as GNOME (XkbOptions) and KDE (set keyboard).

Viewing keyboard settings

You can use the following command to see the actual XKB settings:

$ setxkbmap -print -verbose 10
Setting verbose level to 10
locale is C
Applied rules from evdev:
model:      evdev
layout:     us
options:    terminate:ctrl_alt_bksp
Trying to build keymap using the following components:
keycodes:   evdev+aliases(qwerty)
types:      complete
compat:     complete
symbols:    pc+us+inet(evdev)+terminate(ctrl_alt_bksp)
geometry:   pc(pc104)
xkb_keymap {
        xkb_keycodes  { include "evdev+aliases(qwerty)" };
        xkb_types     { include "complete"      };
        xkb_compat    { include "complete"      };
        xkb_symbols   { include "pc+us+inet(evdev)+terminate(ctrl_alt_bksp)"    };
        xkb_geometry  { include "pc(pc104)"     };
};

Third party utilities

There are some "unofficial" utilities which allow to print specific information about the currently used keyboard layout.

$ xkb-switch
us
$ xkblayout-state print "%s"
de

Setting keyboard layout

Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

Reason: Udev also comes into play (for example when plugging in a keyboard), undoing changes by setxkbmap (Discuss in Talk:Keyboard configuration in Xorg#)

Keyboard layout in Xorg can be set in multiple ways. Here is an explanation of used options:

  • XkbModel selects the keyboard model. This has an influence only for some extra keys your keyboard might have. The safe fallback are pc104 or pc105. But for instance laptops usually have some extra keys, and sometimes you can make them work by simply setting a proper model.
  • XkbLayout selects the keyboard layout. Multiple layouts may be specified in a comma-separated list, e.g. if you want to quickly switch between layouts.
  • XkbVariant selects a specific layout variant. For instance, the default sk variant is qwertz, but you can manually specify qwerty, etc.
  • XkbOptions contains some extra options. Used for specifying layout switching, notification LED, compose mode etc. See the #Frequently used XKB options section for examples.
Note: You must specify as many variants as the number of specified layouts. If you want the default variant, specify an empty string as the variant (the comma must stay). For example, to have the default us layout as primary and the dvorak variant of us layout as secondary, specify us,us as XkbLayout and ,dvorak as XkbVariant.

The layout name is usually a 2-letter country code. To see a full list of keyboard models, layouts, variants and options, along with a short description, open /usr/share/X11/xkb/rules/base.lst. Alternatively, you may use one of the following commands to see a list without a description:

  • localectl list-x11-keymap-models
  • localectl list-x11-keymap-layouts
  • localectl list-x11-keymap-variants [layout]
  • localectl list-x11-keymap-options

Examples in the following subsections will have the same effect, they will set pc104 model, cz as primary layout, us as secondary layout, dvorak variant for us layout and the Alt+Shift combination for switching between layouts. See man xkeyboard-config for more detailed information.

Using setxkbmap

setxkbmap sets the keyboard layout for the current X session only, but can be made persistent in ~/.xinitrc. This overrides system-wide configuration specified following #Using X configuration files.

The usage is as follows (see man 1 setxkbmap):

$ setxkbmap [-model xkb_model] [-layout xkb_layout] [-variant xkb_variant] [-option xkb_options]

To change just the layout (-layout is the default flag):

$ setxkbmap xkb_layout

For multiple customizations:

$ setxkbmap -model pc104 -layout cz,us -variant ,dvorak -option grp:alt_shift_toggle

Using X configuration files

Note: xorg.conf is parsed by the X server at start-up. To apply changes, restart X.

The syntax of X configuration files is explained in Xorg#Configuration. This method creates system-wide configuration which is persistent across reboots.

Here is an example:

/etc/X11/xorg.conf.d/00-keyboard.conf
Section "InputClass"
        Identifier "system-keyboard"
        MatchIsKeyboard "on"
        Option "XkbLayout" "cz,us"
        Option "XkbModel" "pc104"
        Option "XkbVariant" ",dvorak"
        Option "XkbOptions" "grp:alt_shift_toggle"
EndSection

Using localectl

For convenience, the tool localectl may be used instead of manually editing X configuration files. It will save the configuration in /etc/X11/xorg.conf.d/00-keyboard.conf, this file should not be manually edited, because localectl will overwrite the changes on next start.

The usage is as follows:

$ localectl [--no-convert] set-x11-keymap layout [model [variant [options]]]

To set a model, variant or options, all preceding fields need to be specified. Unless the --no-convert option is passed, the specified keymap is also converted to the closest matching console keymap and applied to the console configuration in vconsole.conf. See man localectl for more information.

To create a /etc/X11/xorg.conf.d/00-keyboard.conf like the above:

$ localectl --no-convert set-x11-keymap cz,us pc104 ,dvorak grp:alt_shift_toggle

Frequently used XKB options

Switching between keyboard layouts

To be able to easily switch keyboard layouts, first specify multiple layouts between which you want to switch (the first one is the default). Then specify a key (or key combination), which will be used for switching. For example, to switch between a US and a Swedish layout using the CapsLock key, use us,se as an argument of XkbLayout and grp:caps_toggle as an argument of XkbOptions.

You can use other key combinations than CapsLock, they are listed in /usr/share/X11/xkb/rules/base.lst, start with grp: and end with toggle. To get the full list of available options, run the following command:

$ grep "grp:.*toggle" /usr/share/X11/xkb/rules/base.lst

Terminating Xorg with Ctrl+Alt+Backspace

By default, the key combination Ctrl+Alt+Backspace is disabled. You can enable it by passing terminate:ctrl_alt_bksp to XkbOptions. This can also be done by binding a key to Terminate_Server in xmodmap (which undoes any existing XkbOptions setting). In order for either method to work, one also needs to have DontZap set to "off" in ServerFlags; however, this is now the default.

Swapping Caps Lock with Left Control

To swap Caps Lock with Left Control key, add ctrl:swapcaps to XkbOptions. Run the following command to see similar options along with their descriptions:

$ grep -E "(ctrl|caps):" /usr/share/X11/xkb/rules/base.lst

Enabling mouse keys

Mouse keys is now disabled by default and has to be manually enabled by passing keypad:pointerkeys to XkbOptions. This will make the Shift+NumLock shortcut toggle mouse keys.

Configuring compose key

Though typically not on traditional keyboards, a Compose key can be configured to an existent key.

The Compose key begins a keypress sequence that involves (usually two) additional keypresses. Usage is typically either for entering characters in a language that the keyboard was not designed for, or for other less-used characters that are not covered with the AltGr modifier. For example, pressing Compose ' e produces é, or Compose - - will produce an "em dash": .

Though a few more eccentric keyboards feature a Compose key, its availability is usually through substituting an already existing key to it. For example, to make the Menu key a Compose key use the Desktop environment configuration, or pass compose:menu to XkbOptions (or setxkbmap: setxkbmap -option compose:menu). Allowed key substitutions are defined in /usr/share/X11/xkb/rules/base.lst:

$ grep "compose:" /usr/share/X11/xkb/rules/base.lst

Key combinations

The default combinations for the compose keys depend on the locale configured for the session and are stored in /usr/share/X11/locale/used_locale/Compose, where used_locale is for example en_US.UTF-8.

You can define your own compose key combinations by copying the default file to ~/.XCompose and editing it. The compose key works with any of the thousands of valid Unicode characters, including those outside the Basic Multilingual Plane.

However, GTK does not use XIM by default and therefore does not follow ~/.XCompose keys. This can be fixed by forcing GTK to use XIM by adding export GTK_IM_MODULE=xim and/or export XMODIFIERS="@im=none" to ~/.xprofile.

Tip: XIM is very old, you might have better luck with other input methods: SCIM, uim, IBus etc. See Internationalization#Input methods in Xorg for details.
Note: XIM will prevent insertion of Unicode characters with the Ctrl+Shift+u combination.

Currency sign on other key

Most European keyboards have a Euro sign (€) printed on on the 5 key. For example, to access it with Alt+5, use the lv3:lalt_switch and eurosign:5 options.

The Rupee sign (₹) can be used the same way with rupeesign:4.

Switching state immediately when Caps Lock is pressed

Those who prefer typing capital letters with the Caps Lock key may experience a short delay when Caps Lock state is switched, resulting in two or more capital letters (e.g. THe, ARch LInux). This behaviour stems from typewriters.

Some more popular operating systems have removed this behaviour, either voluntarily (as it can be confusing to some) or by mistake, however this is a question of preference. Bug reports have been filed on the Xserver bug tracker, as there is currently no easy way to switch to the behaviour reflected by those other operating systems. For anyone who would like to follow up the issue, bug reports and latest working progress can be found at [1] and [2].

Workaround

First, export your keyboard configurations to a file:

$ xkbcomp -xkb $DISPLAY xkbmap

In the file xkbmap, locate the Caps Lock section which begins with key <CAPS>:

 key <CAPS> {         [       Caps_Lock ] };

and replace whole section with the following code:

key <CAPS> {
    repeat=no,
    type[group1]="ALPHABETIC",
    symbols[group1]=[ Caps_Lock, Caps_Lock],
    actions[group1]=[ LockMods(modifiers=Lock), Private(type=3,data[0]=1,data[1]=3,data[2]=3)]
};

Save and reload keyboard configurations:

$ xkbcomp -w 0 xkbmap $DISPLAY

Consider making it a service launching after X starts, since reloaded configurations do not survive a system reboot.

Other settings

Adjusting typematic delay and rate

The typematic delay indicates the amount of time (typically in miliseconds) a key needs to be pressed in order for the repeating process to begin. After the repeating process has been triggered, the character will be repeated with a certain frequency (usually given in Hz) specified by the typematic rate. The typematic delay in the virtual console is not affected by these settings.

Using xset

The tool xset can be used to set the typematic delay and rate for an active X server, certain actions during runtime tho may cause the XServer to reset these changes and revert instead to its seat defaults.

Usage:

$ xset r rate delay [rate]

For example to set a typematic delay to 200ms and a typematic rate to 30Hz, use the following command (use xinitrc to make it permanent):

$ xset r rate 200 30

Issuing the command without specifying the delay and rate will reset the typematic values to their respective defaults; a delay of 660ms and a rate of 25Hz:

$ xset r rate

Using XServer startup options

A more resistant way to set the typematic delay and rate is to make them the seat defaults by passing the desired settings to the X server on its startup using the following options:

  • -ardelay miliseconds - sets the autorepeat delay (length of time in milliseconds that a key must be depressed before autorepeat starts).
  • -arinterval miliseconds - sets the autorepeat interval (length of time in milliseconds that should elapse between autorepeat-generated keystrokes).

See man xserver for a full list of X server options and refer to your display manager for information about how to pass these options.

Using XServer options

Tango-inaccurate.pngThe factual accuracy of this article or section is disputed.Tango-inaccurate.png

Reason: The AutoRepeat Option has been removed from the keyboad driver version 1.4.0 https://bugzilla.redhat.com/show_bug.cgi?id=601853#c12 (Discuss in Talk:Keyboard configuration in Xorg#)

Add this line to /etc/X11/xorg.conf.d/00-keyboard.conf:

Option "AutoRepeat" "delay rate"

See also