Reverse detail from Kakelbont MS 1, a fifteenth-century French Psalter. This image is in the public domain. Daniel Paul O'Donnell

Forward to Navigation

Custom Keyboard in Linux/X11

Posted: Dec 09, 2006 14:12;
Last Modified: Apr 04, 2021 12:04


tl;dr (works as of Ubuntu 16.04)

  1. edit/create a keyboard in /usr/share/X11/xkb/symbols/ (mine is here)
  2. add definition for keyboard to /usr/share/X11/xkb/rules/evdev.xml (here’s my file)
  3. reboot
  4. add keyboard to Settings > Language and Region > Input Sources (I don’t know what files that interface changes)
  5. assign “third level” shifter and “compose” keys using System Settings > Keyboard > Shortcuts (The GUI menu is now [Jan 2021] only available from Gnome Tweaks, but it doesn’t make a persistent change; to make a chooser persistent see the note below under “Third-level chooser”)
  6. Bob’s your uncle.

There were a number of problems with using this method in Ubuntu 14 and 15. They seem to be solved now.


  • I’m a Mac/Windows/Chromebook/Android etc. user: how do I create a custom keyboard?
  • Introduction

    As an early medieval English philologist, I make daily use of a number of characters that are not found on the standard US computer keyboard. These include characters and accented letters from various European languages (e.g. ß, é, ä, ø), IPA symbols (e.g. ŋ, ә, etc.), Middle English ȝ, and various letters and forms used in Old English (æ, þ, ċ, ġ, ƿ, ū, ȳ, etc.).

    It is possible to gain access to these letters from the character map utility (versions of this are found in all operating systems) or from the “Insert Special Characters” function in my word processor. But for characters I use all the time, this is quite tedious and time consuming. If I am typing Old English, I want to be able to access the “special characters” I use most often from the keyboard. Characters consisting of a single glyph (e.g. æ, ß, þ, ð), I want to be able to enter from the keyboard directly; accented characters (e.g. è, ü, ȳ), I want to be able to build (compose) from their component parts (e.g. type ` and e to get è1. I also want to be able to use these characters in all programs and utilities on my computer: in my email client, from the command line, in programs and utilities that do not have a “insert special characters” menu item.

    Fortunately, it is quite easy in X-11 based Linux distributions to create both custom keyboard layouts (for typing individual characters) and custom compose sequences (for building characters from their component parts)2.

    The following shows how I customised my keyboard and compose sequences in Ubuntu. Ubuntu (or perhaps Gnome?) changed things between Ubuntu 8.04 and 8.10, so you need to do things slightly differently depending on which version you are using. The same techniques should work in other X11-based distributions, although different distributions have the files in different places (see, for example, comment 8 below for Fedora 8).

    This material is derived primarily from discussions at the following URLs:

    In adding material on Ubuntu 8.10, I am indebted to the comments by jv and raek, below. Thanks very much.

    Customising the keyboard layout

    Customising the keyboard layout involves four or five steps that vary depending on your distribution:

    1. Creating a custom keyboard layout in X11/xkb/symbols/ (here’s my original and my latest). 3
    2. Modifying the configuration files
      1. ≤ Ubuntu 8.04: X11/xkb/rules/xorg.xml (here’s mine) and (optionally) X11/xkb/rules/xorg.lst (here’s mine)
      2. ≥ Ubuntu 8.10: X11/xkb/rules/evdev.xml (here’s mine)
    3. Other cleanup and enabling
      1. ≤ Ubuntu 8.04 (not necessary in ≥ Ubuntu 8.10): Modifying the combination key bindings (i.e. the strokes that produced composed keys such as ȳ) X11/locale/en_US.UTF-8/Compose copied to /home/$USER/.XCompose and modified if necessary (here’s mine)
      2. Invoking the new evdev, either by sudo dpkg-reconfigure xkb-data or by deleting the xkm files in /var/lib/xkb and either logging out and back in or just switching to a new layout and back (see here for details)
    4. Designating “third level chooser” and “compose” keys in Gnome.

    When you design your custom keyboard, you might want to keep some of the national, ISO, or SIL keyboards in mind: there’s no point learning an idiosyncratic keyboard layout if something already exists that covers what you want. For national and ISO standards, the Wikipedia article Keyboard Layout is a good place to start. For SIL, you can start at their resources page

    Creating a custom keyboard layout

    In X11 systems, keyboard layouts are kept in the X11/xkb/symbols directory (in Ubuntu, the full path is /etc/X11/xkb/symbols (≤ Ubuntu 8.04) or /usr/share/X11/xkb/symbols (≥ Ubuntu 8.10); the top level directory may be different in other distributions).

    Each of the files in this directory contains a series of entries of the following type:

    key <AC01> { [ a, A, aacute, Aacute ] };

    This entry maps a key on the keyboard to a number of specific characters using the following conventions:

    1. The first two letters after key indicate where the key is found: The first letter indicates we are looking in the alphanumeric key block (other options include KP [for keypad] and FK [for Function Key]); the second indicates the row, counting from the bottom in which the key is found. (In a standard US keyboard, the space bar is in row AA and the number keys are in row AE).
    2. The next two numbers indicate the position of the key, counting from the left and ignoring any specially named key like <TAB> or <TLDE> (tilde): AC01 is in the third row up, first key over from the left (ignoring CapsLock, if present); on a standard US keyboard, this is the key marked “a”.
    3. The brace and square brackets enclose the list of characters assigned to each key. This can contain between one and four entries, separated by commas.
      1. The first entry is for the unmodified key (i.e. what happens when you press the key by itself)—in this case a.
      2. The second entry is for the shifted character (i.e. what happens when you press the key in question and <shift> at the same time)—in this case A.
      3. The third entry is for the “third level” character (accessed when you press the key with a “third level chooser” (see below)—in this case á.
      4. The fourth entry is for the shifted “third level” (i.e. when you press the key at the same time as <SHIFT> and the “third level chooser”—in this case Á.

    Creating a custom keyboard map is as easy as replacing the characters you don’t want in a given line with the ones you do. As an early medieval English specialist, I type á and Á much less frequently than I type æ and Æ, for example. To add the Old English characters to my list, I simply replace aacute and Aacute with the entity names or Unicode code points for æ and Æ (“aelig” or U00E6 and “AElig” or U00C6, respectively). Note that in the comments, Jedd Schrock records having difficulty with entity names for some characters, whereas the Unicode points always work; perhaps for anything other than the most common characters, it is just easier to use the code points:

    key <AC01> { [ a, A, aelig, AElig ] };


    key <AC01> { [ a, A, U00E6, U00C6 ] };

    When I am finished modifying my keyboard layout, I save the file with a new name (in my case oe in the X11/xkb/symbols directory.

    Adding a new keyboard layout to xorg.xml (≤ Ubuntu 8.04)/evdev.xml (≥ Ubuntu 8.10) and xorg.lst

    In order to use my new keyboard layout, I need to tell X11 that it exists. X11 keeps track of installed keyboards in one of two configuration files: X11/xkb/rules/xorg.xml (Ubuntu 8.04 and lower) or X11/xkb/rules/evdev.xml (Ubuntu 8.10 and higher) (There is also a file /etc/X11/xkb/rules/xorg.lst that seems to contain similar information; it doesn’t seem to be used in any recent version of Ubuntu).

    X11/xkb/rules/xorg.xml (≤ Ubuntu 8.04)

    To add a keyboard layout to X11/xkb/rules/xorg.xml (i.e. for use in Ubuntu 8.04 and lower):

    1. Open X11/xkb/rules/xorg.xml in an editor
    2. Go to the end of the <layoutList> section (search for </layoutList>). Add the following after the last </layout> tag, where x is the file name of your keyboard layout in X11/xkb/symbols (in my case Old English); y a suitable short name (in my case OE); and z an appropriate long name in one or more languages (in my case “Old English”):
               <name> x </name>
               <shortDescription> y </shortDescription>
               <description> z </description>
    X11/xkb/rules/evdev.xml (≥ Ubuntu 8.10)

    To add a keyboard layout to X11/xkb/rules/evdev.xml (i.e. for use in Ubuntu 8.10 and higher):

    1. Open X11/xkb/rules/evdev.xml in an editor
    2. Go to the end of the <layoutList> section (search for </layoutList>). Add the following after the last </layout> tag, where x is the file name of your keyboard layout in X11/xkb/symbols (in my case Old English); y a suitable short name (in my case English philologist); z an appropriate long name in one or more languages (in my case English philologist), and aaa a legal three letter (ISO 639-2) language code (e.g. eng for English) (Do not leave spaces between the tags and the names you are using: the system still works if you do, but there are display issues):
               <name> x </name>
               <shortDescription> y </shortDescription>
               <description> z </description>
                  <iso639Id> aaa </iso639Id>
    X11/xkb/rules/xorg.lst (optional)

    For sake of consistency, you may want to edit X11/xkb/rules/xorg.lst to reflect the settings in X11/xkb/rules/xorg.xml (As far as I can tell, not doing so does not affect anything, but who knows?).

    1. Open X11/xkb/rules/xorg.lst in an editor.
    2. Find the section that begins ! layout
    3. At the end of this block add the file name your keyboard layout has in X11/xkb/symbols and a long-text description of your keyboard (in my case these are oe and Old English respectively).

    Assign “Third-Level Chooser”

    Note (Jan 2021): I’ve been having trouble with this for a while: I could only access the keyboard menu described below using Gnome Tweaks (it’s no longer available from settings) and nothing I chose there seemed to “stick” — every time I rebooted, the third level choser (and dead key selecter stopped working and the only solution was to go in and reselect it in “Tweaks” (i.e. by selecting a dfferent key, returning, and then saving).

    I discovered a solution (don’t remember where), which is to add the following at the end of my keyboard layout (it is now in the layout available from this page:

     partial alphanumeric_keys
     xkb_symbols "euro" {
         include "us(basic)"
         name[Group1]= "English (US, euro on 5)";
         include "eurosign(5)"
         include "level3(ralt_switch)"

    Since adding this, I’ve had no problems.

    Note (March 2021): Myke adds two comments below that suggests that the above code is more than is needed (edited to capture his intention):

    I have noticed that many of the standard keyboards integrate the ‘level3(ralt_switch)’ directly from the ‘level3’ package, without the ‘euro’ component. i.e. they include the reference within the layout paragraph, at the very end.

    The Italian, for example, has:

    key <LSGT> { [ less, greater,guillemotleft,guillemotright] }; include “level3(ralt_switch)” };

    as the last line in its ‘basic’ paragraph

    I hope to try this out next time I update the keyboard.

    What follows is the previous instructions….

    The final stage is to designate a “Third Level Chooser” key to allow you to access the characters you have just added to your keyboard. In Gnome-based systems like Ubuntu, this is probably best done from the menu bar:

    1. Open the Keyboard menu (System > Preferences > Keyboards)
    2. Select the “Layouts” tab
    3. Click the “Add” button
    4. Choose your custom layout from the alphabetical list of available layouts and click “OK”. If you want this working every time you log in, check the “default” option.
    5. Select the “Layout Options” tab
    6. Expand the “Third-Level Choosers” list entry
    7. Choose the key you want to use as a “Third Level Chooser”4
    8. Click on the “Close” button

    You should be able to access your custom keys immediately. If you find that they are not working, reset X11 by logging out and back in. At that point they should work fine.

    Customising compose key sequences.

    Note: I am not sure is this section (except for assigning a compose key in Gnome) is necessary in Ubuntu 8.10+).

    Gnome provides access to hundreds of compose key sequences by default, though getting a list of these sequences can be quite difficult.

    While the default key bindings are almost certainly enough for typing most modern languages, you may discover one you need is missing, or wish to use a different set of keys. In such cases, you will need to add or modify the compose key sequences.

    Apparently (, this list of compose key bindings cannot be edited5. To get around this, you set the text input method to xim and create a custom list of compose key bindings. This sounds harder than it is:

    Changing the input method to xim

    1. Open /etc/environment in an editor
    2. Add export GTK_IM_MODULE=xim to the end and save.

    Creating a list of keybindings

    1. Copy the X11 compose-key bindings for your keyboard to your home directory (for US keyboards cp /usr/share/X11/locale/en_US.UTF-8/Compose ~/.XCompose; for other locales, see the options available in /usr/share/X11/locale/
    2. Open ~/.XCompose in an editor. The file consists of a series of lines that map character combinations to Unicode code points, e.g. <code><Multi_key> <macron> <U> : "Ū" U016A # LATIN CAPITAL LETTER U WITH MACRON
    3. Edit/Add key sequences (e.g. <Multi_key> <minus> <Y> : "ȳ" U0233 # LATIN SMALL LETTER Y WITH MACRON (Tip: this file contains a number of references to characters you probably don’t have set up in your keyboard, such as <macron> in key bindings for characters like ē. In my case, I changed all examples of <macron> to <minus>.
    4. Save file.

    Assign “Compose key”

    The final stage is to designate a “Compose Key” key. This is the key that indicates the next keys are part of a compose key sequence.

    1. Open the Keyboard menu (System > Preferences > Keyboards)
    2. Select the “Layout Options” tab
    3. Expand the “Compose Key” list entry
    4. Choose the key you want to use as a “Compose Key”
    5. Click on the “Close” button.

    You will need to log out and back in before your settings take effect. After you have logged back in, you should be able to use your new compose key sequences.

    Resetting the keyboard

    This no longer (as of 16.04) seems to be necessary. The keyboard loads on reboot.

    I’ve had trouble with changes not taking effect. According to this forum entry, the only way of doing this is to eliminate the all the *.xkb files in /var/lib/xkb and then restart the windows manager (in post-Unity versions of Ubuntu sudo restart lightdm). I have since found that the lightdm restart does noting (i.e. starting in in 16.04). A different page suggested using sudo dpkg-reconfigure xkb-data.

    I did this by creating a new directory for the old files, then moving them to that directory, then restarting the manager.

    It works.

    I’m a Mac/Windows/Chromebook/Android etc. user: how do I create a custom keyboard?

    The short answer is that I don’t know: the method discussed here only works with the X11 windows manager, which means only in Linux. But here’s some resources to help you find out how to do this or something similar in other operating systems:


    1 I make this distinction because I don’t type accented characters enough to make it worth my while to treat accented characters as single glyphs. If I found myself typing characters like ü very often, I could easily add them to my keyboard in the same way I add characters like æ or ß.

    2 Windows, pre-OS X Macs (and to a lesser extent Mac OS X) handle keyboard mapping differently. Utilities exist that either allow you to create custom keymaps or use keymaps that cover common specialisations (e.g. for linguists who need to type IPA. You can find more about these solutions by searching for terms like “keyboard” “custom” “keymaps” and “Windows” or “Mac”.

    3 The top level directory for this path varies from distribution to distribution. In Ubuntu ≤ 8.10, the full path is /etc/X11/xkb/symbols/; in In Ubuntu ≥ 9.04 it is /usr/share/X11/xkb/symbols/. There are other changes in the contents of these files. You are better modifying the version on your system than downloading my copies of evdev, etc. The keyboard layout file itself should work fine if you download it. Just make sure you change the name to match the contents of the <name> element in evdev.xml.

    4 For reasons that are not clear to me, some programs (most notably Evolution) fail to recognise “Third Level Choosers” if you deselect “Right Alt”—the safest way to go is to use right alt as your third level chooser or make two keys your third level chooser: right alt and some other key of your choosing.

    5 Actually I doubt this is true, but the method I’m describing here works for me and proved easier than discovering how to do it within Gnome.


    Comment [73]

    1. Mate (Mon Jan 29, 2007 (12:23:44)) [PermLink]:

      Thank you very much! I searched for a tutorial exactly like this! Mate from Hungary.

    2. Jan (Mon Apr 9, 2007 (16:23:51)) [PermLink]:

      Thanks for your tutorial. I’ve used it to define a new layout, but i’m having trouble using combined diacritics to accent all vowels. Do i define the character combinations somewhere else?

    3. Dan O'Donnell (Tue Apr 10, 2007 (12:40:07)) [PermLink]:


      I’m not sure exactly what the nature of your problem is:

      * do you mean that certain combinations of combining diacritics are not working?

      * Or that you want to add new combinations that don’t exist

      * Or that you want to add precomposed characters to your keyboard layout?

      * Or something else?

      The thing to keep in mind to start with is that composition and key assignments are different: if you want to get a composed character in one key stroke (with or without a second or third level chooser), you add it to a custom keyboard; if you want to be able to compose on the fly, you use a compose key (different from your third level chooser) and then two other keys—for the diacritic and for the letter it combines with.

      If the issue is that you don’t know how to combine certain diacritics with certain letters, all I know is written out above in the section “Customising compose key sequences.” I found it a more tedious question of ploughing through ~/.XCompose.

    4. neo (Fri May 18, 2007 (12:45:17)) [PermLink]:

      Anyone has done this successfully in Debian? I found out there is no xkb, etc. setting located in the X11 folders. What should I do in order to get it worked under Debian testing?

      Many thanks.

    5. dan (Fri May 18, 2007 (17:28:14)) [PermLink]:

      I’m assuming you mean pure debian rather than the Ubuntu fork/variant?

      I don’t know. I just checked and Ubuntu Feisty still has the directory under /etc/X11. I don’t have a spare computer available to install straight Debian and see what happens.

    6. Daniel (Mon Mar 17, 2008 (20:46:46)) [PermLink]:

      Been trying to make my own layout it’s got 6 levels (english, latin, greek)
      Plus its Dvorak. anything above 4 levels seams to be undocumented so I found the canadian layout which uses 6 levels (8 levels possible) email me at yellow_onion at if you want to perhaps update your tutorial and be the first to document it

    7. ivan (Thu Apr 17, 2008 (15:42:35)) [PermLink]:

      thanks, i needed some custom layout for Java programming, this is absolute winner tutorial

    8. linuxbee (Thu May 8, 2008 (20:58:39)) [PermLink]:

      in Fedora 8, the path is given by:

    9. Dan O'Donnell (Tue May 20, 2008 (09:33:20)) [PermLink]:

      I reported that “this method doesn’t seem to work in versions 7.10 or 8.04 from a clean install. Part of the problem seems to be that Ubuntu now has the X11 material in two places and uses different names for some of the files.”

      But I was wrong: the trouble was I changed the name of the file and it wasn’t loading properly. The method works just fine on new Ubuntu installs of 7.10 and 8.04.

    10. Josh (Fri May 30, 2008 (23:21:27)) [PermLink]:

      Spectacular! It took me a while to find, but worth every second!

      I Used it to change the <MENU> key to a <KPDL> “KP_Delete” key in Ubuntu 8.04

      At first I was a little confused how the layout file was tied to the xorg.xml file. I eventually got everything to work, then of course saw Note #4.

      Your xorg.xml file has “<name>Old English</name>” instead of “<name>oe</name>” as Note #4 implies.

    11. dan (Sun Jun 8, 2008 (16:44:00)) [PermLink]:

      Thanks very much: I’ve fixed the note.

    12. ABU SAUD (Thu Jun 19, 2008 (22:41:55)) [PermLink]:

      I have some problem in xml unicode entities….i con’t access some entities and utilities in linux os server pls…help me….mail me to

    13. dan (Mon Jun 23, 2008 (23:56:40)) [PermLink]:

      Sorry. I don’t know what you mean!

    14. Petr (Sat Aug 16, 2008 (07:22:40)) [PermLink]:

      I need to define diferent compose keys in diferent for diferent layouts. Could you help me? The same key combination should get č when the Czech is elected, but ĉ, when I am using the layout for Esperanto.

    15. dan (Sun Aug 17, 2008 (23:25:11)) [PermLink]:

      I believe this is possible from within the key layouts themselves, but I confess I don’t know how to do it. You could look through all the various files in the symbol directory looking for compose keys.

      But are you sure you want the same key strokes for these? I can see how it might be handy to keep the two accents separate so that you can use them in typing other languages in both keyboards… e.g. French and/or American Phonetic Alphabet.

    16. dan (Sun Aug 17, 2008 (23:31:23)) [PermLink]:

      A follow up: Have you thought of the first approach listed under Linux here:

    17. Elmer (Sat Sep 20, 2008 (20:04:03)) [PermLink]:

      Great information. I am trying to get tengwar (language developed by J.J.R. Tolkien for Lord of the Rings) working on my Ubuntu 8.04 and so far it is going ok. The problem with tengwar is even though fonts are available for the characters, it uses the US standard keyboard. You can activate the fonts (I do this by using gvim and then selecting one of the tengwar fonts I installed in ~/.fonts) and then gvim uses the US standard keys to select which font to display. There is really no keymap. I am going to develope a tengwar keymap that takes into account what the most common tengwar symbol usage frequency.

      This is the same concept as the Dvorak keyboard.

      anyhow thanks a lot for your article.

    18. tims (Thu Oct 30, 2008 (06:20:31)) [PermLink]:

      As a technical writer, I appreciate how clearly you have explained things. As a dabbler in West African scripts, this will be most useful. Thanks!

    19. jv (Thu Nov 20, 2008 (13:37:32)) [PermLink]:

      I just installed the latest Ubuntu version 8.10 (Intrepid) and have been trying to get these things working. I have found out that the X11 directory has moved to /usr/share/ and that the files evdev.xml and evdev.lst are the right ones to modify now. I still haven’t been able to make new independent layouts show up in Gnome, but only variants. That’s not a big problem, but if someone finds out a way, I would be happy to know about it.

    20. dan (Thu Nov 20, 2008 (22:22:05)) [PermLink]:

      Thank you very much. I’ve just installed a couple of 8.10 versions and haven’t been able to figure out where things are yet.

      You’ve seen that the symbols directory is under xkb, right? Presumably that’s where you drop the new layouts.

      I also see the old xorg.xml and xorg.lst in that directory. Are you sure changing them doesn't work as of old?

    21. jv (Mon Nov 24, 2008 (11:30:23)) [PermLink]:

      At least the first time I got something new to show up in the Gnome selector was when I added a variant in evdev.xml.

      It seems the selection is now based on country or language. I think they used to be just layouts before (but typically named after countries). I also got an independent layout file working by adding a with <span class="caps">ISO</span> country codes in evdev.xml. That way the layout still appears under the chosen country/countries. I’m happy with that, as the panel indicator is now showing my own , which is more descriptive than the country code.

    22. dan (Tue Nov 25, 2008 (09:43:33)) [PermLink]:

      You’re right. I wasn’t able to get anything working in xorg.xml (which is basically the same format as evdev.xml). But I’m not getting things right anyway.

      You wouldn’t want to post an example of how you got it to work with the ISO names, would you?

    23. jv (Tue Nov 25, 2008 (15:38:09)) [PermLink]:

      Oh, the xml elements were dropped from my post. Just search for countryList in evdev.xml for an example. There are some japanese, arabic and latin american layouts with countryLists. I added same kind of countryList with the iso3166Id of my home country and found the layout in the corresponding section of the Gnome selector.

    24. Owaqpzru (Sat Dec 13, 2008 (11:25:33)) [PermLink]:


    25. Nico de Berlin (Sun Feb 8, 2009 (13:17:36)) [PermLink]:

      Great ! i was always puzzled by all these configuration files. Very clear tutorial. ThX !

      Made for polish letters with a german QWERTZ keyboard.

    26. dan (Sun Feb 8, 2009 (18:04:45)) [PermLink]:

      Did you get it working in 8.10? I haven’t! What did you do?

    27. Tova (Thu Mar 12, 2009 (12:25:38)) [PermLink]:

      Thank you very much for this very clear tuto ! It allowed me to type these darned Old Norse names far more easily. Sincere thanks from all the Óláfs !

    28. raek (Thu Mar 12, 2009 (15:28:40)) [PermLink]:

      I managed to get my layout working in Ubuntu 8.10:
      1) Place the symbol file in /usr/share/X11/xkb/symbols/.
      2) Edit the /usr/share/X11/xkb/rules/evdev.xml file.
      3) Add your layout to the file as described in this page.
      4) After ‹/description›, add ‹languageList›‹iso639Id› language ‹/iso639Id›‹/languageList›, where language is an existing language code, for example “eng” – English or “art” – Artificial. If you choose a non-existing language id, or omit it all together, your layout won’t appear in the Gnome selector.

      (NOTE: i used angle quotes instead of angle brackets in the XML tags in this post due to technical restrictions, so don’t copypaste these characters into your configuration file.)

      Thanks for the great tutorial, Dan!

    29. Daniel (Fri Mar 13, 2009 (05:59:06)) [PermLink]:

      Cannot find the files mentioned on Ubuntu 8.10 :(

    30. dan (Fri Mar 13, 2009 (19:00:50)) [PermLink]:

      Raek… this worked like a charm for me. Thanks very much. I’ve been missing my custom keys since last October!

    31. dan (Fri Mar 13, 2009 (19:08:45)) [PermLink]:

      Daniel: all the files (including those mentioned in Raek’s post) are found on my clean Ubuntu 8.10 install. How are you looking for them? From the command line? In Nautilus? Could it be in this later case that you need to work as root/sudo?

    32. oeb (Mon Mar 16, 2009 (12:10:13)) [PermLink]:

      how would one change the third level chooser to the [space-bar] for implementing a one-hand qwerty setup as in: ?

      the space-bar isn’t a choice in ‘layout options’. I’m using hardy-lts, which uses the X11-xkb-utils and not xkbcomp.

    33. dan (Mon Mar 16, 2009 (21:05:23)) [PermLink]:

      Perhaps something in /home/$USER/.XCompose?

      I’ve not had much luck overriding gnome, though.

    34. Nazar (Wed Mar 18, 2009 (09:40:05)) [PermLink]:

      Thanx, great tutorial.

      All i could add is the link to language ids referred by reak :

    35. dan (Wed Mar 18, 2009 (10:14:00)) [PermLink]:

      I’ve now updated the instructions to cover &#x2265;Ubuntu 8.10.

    36. John (Fri Mar 20, 2009 (19:55:10)) [PermLink]:

      Thanks for the tutorial.
      My files were in /usr/share/X11.

    37. ThierryM (Fri May 8, 2009 (07:18:37)) [PermLink]:

      Thank you very much for this tutorial. Under Ubuntu Jaunty 9.04, I had to modify the file /etc/X11/xkb/base.xml . I described how I made here in french :

    38. BulatY (Sun May 31, 2009 (11:54:45)) [PermLink]:

      Thank you very much. This tutorial make possible to define bashkir layout (russian ciryllic with some original characters) in Linux.

    39. Nico der Berliner (Tue Sep 22, 2009 (04:29:24)) [PermLink]:

      Thanks a lot for this very clear tutorial. I could finally create a Variant with polish letters to my german QWERTZ keyboard.

    40. Luzi (Tue Nov 24, 2009 (01:38:57)) [PermLink]:

      With the help of your instructions, I managed to design my own keyboard layout for Old Germanic
      So: [‘θæŋks]!

    41. Mariusz (Wed Nov 25, 2009 (14:14:05)) [PermLink]:

      An excellent and a very much needed tutorial.

      Do you know how to add a new keymap without root privilages?

      If you know or find out, would you be so kind to post the instructions? That would be doubly useful as many of us use Linux workstations at various scholarly institutions around the world as ordinary users who cannot modify any of the system files.

    42. dan (Fri Nov 27, 2009 (15:25:24)) [PermLink]:

      I don’t know that, but you’re right that it would be good to know. I’ll keep an eye out to see how one can override system wide settings in one’s own account. It is presumably possible.

    43. hajder (Sun Feb 28, 2010 (12:39:53)) [PermLink]:

      temporarily you can set it by typing “setxkbmap “
      or xmodmap

    44. poacheR (Fri Feb 18, 2011 (14:47:54)) [PermLink]:

      I’m trying to enable putting acute accents on russian (cyrillic) characters. I’ve had problems with the compose key that I won’t go into, so I’m trying to avoid that for now. I’ve had luck with editing the /usr/share/X11/xkb/symbols/ru file, and replacing the semicolon with U0301 (i.e.a non-spacing acute accent).

      For some reason, I always have to reload the keyboard after a login, before the accent gets activated, but it works. Now I can accent russian letters by pressing the key and then the semicolon key: о́чень хорошо́!

      What I was wondering is if there is a way to input composed unicode characters directly. Xkb throws an error if I try to insert a composed character, e.g. U0061 U0301 instead of, say, U00E1. Is it a matter of a syntax error on my part? Or can you not compose characters directly like that in the config file?

      (what I’m after would be to press the third-level key and the cyrillic vowel, and result in an accented cyrillic vowel)

      Спаси́бо, Dan!

    45. stan (Thu May 12, 2011 (18:31:14)) [PermLink]:

      poacheR – As far as I know, what you want to do is impossible. However, you should be able to put in the single equivalent unicode character in your keymap.

      I just stopped to thank Dan for posting these instructions. They still work on Fedora 14. It is possible to use them for either a variant (rules/evdev.xml and symbols/us) or a standalone keymap (rules/evdev.xml and symbols/my_keyfile). During development,I had some errors in my keymap, and the X error messages in the popup weren’t helpful. I ended up booting to runlevel 3, console only, and testing with startx. As a normal user, running the command startx > startx_output 2>&1 . When I logged out of X, I was able to see the error messages saved in the file and fix the problem. Maybe this will help someone else.

    46. JTSchrock (Fri May 20, 2011 (18:53:36)) [PermLink]:


      Thanks so much for this tutorial. It has been the one tool I’ve found useful so far for creating custom keyboards in Ubuntu.

      However, I am still having some difficulties. I’ve followed the steps you outline above, up to the third level chooser and Xcompose sections. (the keyboard I am making doesn’t have need for more than two levels). I also added:

      cj Chinook Jargon

      to the !layout section of xorg.lst and xorg.xml.

      After I add my layout file to ..X11/xkb/symbols and change the evdev.xml file I get the following error window:

      Error activating XKB configuration.
      It can happen under various circumstances: • a bug in libxklavier library • a bug in X server (xkbcomp, xmodmap utilities) • X server with incompatible libxkbfile implementation

      X server version data:
      The X.Org Foundation

      If you report this situation as a bug, please include: • The result of xprop -root | grep XKB • The result of gconftool-2 -R /desktop/gnome/peripherals/keyboard/kbd

      I am using Ubuntu 11.04. After I’ve added the cj layout file and listed it in evdev.xml, I go to set my keyboard preference “Chinook Jargon” (that’s my target language). Remarkably, Chinook Jargon does show up as a permissible language, and even when I choose is in the “choose layout” window, the proper layout is displayed on the keyboard graphic. Once I click “add” the error message pops up. This makes me think there are additional steps that I must take to satisfy all of xkb’s requirements.

      I tried a workaround to test my layout file. I sudo’ed into ../xkb/symbols/bgr. Opened bgr in gedit, erased the first alphanumeric section, and pasted in the text from my cj layout file. Loaded Bulgarian as a keyboard in the preferences section, and away I typed in Jargon. This confirms that I’m missing a step or two in registering everything correctly within the xkb system.

      Would an absent third-level chooser cause this glitch? Xcompose?

      Thanks for any thoughts

      hayu masi pus munk-tʼsəm ukuk ɬush tʼwax̣-iliʔi!

    47. Sagar Behere (Wed May 25, 2011 (05:40:48)) [PermLink]:

      Thanks! This is exactly what I was looking for :)

    48. dan (Mon Jun 6, 2011 (18:36:10)) [PermLink]:

      First of all, JT, we should meet up: we must be very close to each other and I’m extremely interested in Chinook Jargon.

      As to the rest of your questions, I’ll need to check. Hopefully tomorrow.

    49. raek (Sat Jun 18, 2011 (04:30:00)) [PermLink]:

      Hello again!

      I thought I’d share a link to the Ubuntu Community Documentation that I just found:

      Howto: Custom keyboard layout definitions

      It seems to be similar to this page, but not as detailed. It does however point to the files you should edit in recent versions of Ubuntu and has some good links.

      Again, thanks for a great tutorial!

    50. Jaaf (Sat Aug 6, 2011 (08:07:17)) [PermLink]:

      Thanks for this very clear tutorial.
      I attempted to do as you say under Ubuntu 11.04 (Gnome). I took your file oe and put it in /usr/share/X11/xkb/symbols and modified evdev.xml and evdev.lst as you say.
      I did nothing else (no compose ans no third level chooser). Unfortunately after log out and back in again. I can’t find Old English in System > Preferences > keyboard.
      Any suggestion would be welcome.

    51. DirkL (Mon Apr 6, 2015 (16:23:21)) [PermLink]:

      In Ubuntu 14.04, maybe before (I only use LTS releases) the ability to
      reassign Level 3 Chooser is no longer available. Probably upstream
      Gnome decision. Only workaround that I could find is to run *sudo
      dpkg-reconfigure keyboard-configuration* which redefines the
      system-wide default.

      Also, restarting the window manager is only necessary if you have
      changed evdev.xml. If you have only changed files in symbols,
      says you can type

      udevadm trigger —subsystem-match=input —action=change

      It goes without saying that you should make a script file for that!

    52. Yuta (Fri Aug 3, 2018 (16:52:11)) [PermLink]:

      Thank you for the excellent instruction! It was clear and easy to follow. Worked like a charm, too = )
      Things like this are the reasons I love linux so much

    53. NIRANJAN TAMBE (Wed Jul 3, 2019 (12:33:12)) [PermLink]:

      Hello sir. Can I dump a combination of characters (or a character and a diacritic) together on one key?

    54. Michael (Wed Oct 23, 2019 (17:09:46)) [PermLink]:

      Anyone know how to do this on Xubuntu 18.04 or LMDE? Doesn’t seem to work on these.

    55. leo (Sun Apr 26, 2020 (05:05:52)) [PermLink]:

      Still updated… worked great for me.

      my Lenovo Ideapad 17 has a broken keyboard.. getting a replacement… really a pain in the rear. I had an external.. but not really a laptop the.. so I decided to mapp normal numeric line AD01 .. AD09 to replace the keys that stppped working.
      Finish with a numeric line that uses the 4 columns for map letters, numbers, acute and characters.

      One question that could be helpful for others, I could not find what are the positions for the numeric keyboard on the right side, maybe AD15 – AD18 to AF15 – AF18 ?

      Did not try it that as with current configuration and while I get a replacement keyboard, I am satisfied with end particular keyboard.

      Do you know how are referenced in an EN x11/symbols file standard keyboard?


    56. javid (Sun Jun 7, 2020 (12:19:45)) [PermLink]:

      I try to added Persian layout on ubuntu xfce4 descktop and I select Win+Space from Change layout option but it changes at first from English to Persian but after that it does not work to switch from Persian to English.

    57. javid (Sun Jun 7, 2020 (12:19:45)) [PermLink]:

      I try to added Persian layout on ubuntu xfce4 descktop and I select Win+Space from Change layout option but it changes at first from English to Persian but after that it does not work to switch from Persian to English.

    58. Joe (Wed Jun 17, 2020 (09:04:55)) [PermLink]:

      Does this still work nowadays? I’m pretty sure I did everything the way you said, however my layout doesn’t show up in the settings.

    59. Dan O'Donnell (Fri Jun 19, 2020 (10:05:28)) [PermLink]:

      Joe: Yes, just used it today. Updated the instructions a little, but I don’t quite know how to find the third-level chooser anymore. It just seemed to remember for me. Maybe it’s in the keyboard now? Don’t remember.

    60. Dan O'Donnell (Fri Jun 19, 2020 (10:07:50)) [PermLink]:

      Hi Javid. I’m afraid I don’t know the answer: this is one of these things where my knowledge is no reduced to what is written here. It still works for me is all I know.

      Good luck and let me know if you do solve it. We can add something here.

    61. Jedd Schrock (Sat Jul 25, 2020 (08:54:18)) [PermLink]:

      Hi Paul,

      I’m trying to make a keyboard for typing Chinuk Wawa (Oregon, Native American). I’ve followed the steps you’ve described here, but I’m having some hang-ups.

      I’m working in Linux Mint 20. Xedit is the default text editor in Mint.

      I created a layout called “chn” and put it in the /x11/../symbols/ folder. I also added my layout to evdev.xml. (doing all of this as root). I am pasting the syntax you show above for the evdev.xml file. When I edit my evdev file, my terminal (where I sudo thunar to get to my root file manager) immediately shows an error message :

      • (xed:2342): WARNING **: 07:11:54.661: Set document metadata failed: Setting attribute metadata::xed-spell-language not supported
    62. It’s like I’m breaking my evdev.xml file by editing it. Maybe I can’t do this in Xedit? Weird. Once I reboot, my chn keyboard does show up in settings->keyboard->layout, but I can’t switch to it. English still works but no switching happens. It’s like X11 acknowledges the file is there but maybe it’s corrupt or something. Anyway, any thoughts you have on this would be greatly appreciated.

    63. Dan O'Donnell (Sat Jul 25, 2020 (21:33:59)) [PermLink]:

      Dear Jedd,

      Sorry. I’m not sure. Given that it happens immediately, and it’s an xed error, I wonder if you shouldn’t try a different editor, in case this one is trying to add something. I use nano (a bash editor) for a lot of this stuff, or gedit (a more GUI-one, and I’ve never had this issue.

      Perhaps report back if you fix it?

    64. Jedd Schrock (Tue Jul 28, 2020 (15:42:33)) [PermLink]:

      Hi Paul,

      Thanks for your reply.

      Using Gedit did get rid of those errors upon saving. But my keyboard still won’t switch.

      I first tried switching to a German keyboard (German layout already in XKB)to make sure switching works generally on my system. No problems there.

      Then I installed your oe keyboard (from this page) just to see if I could load a custom keyboard. That also works/switches fine.

      So given all this with the fact that my cw (Chinuk Wawa) layout shows up as an option, but switching to it doesn’t work, makes me think there is something wrong with the syntax in my cw.txt layout file.

      What glyph names am I supposed to use for the characters? My layout currently has all my special characters listed as Unicode values like U0313 for combining comma above. Maybe XKB has character naming requirements that I don’t know about.

      Maybe I’m missing something with commas or other delimiters? Here is a section:

      key <AD01> { [ q, Q, Q ] };
      key <AD02> { [ w, U02B7, U028D, W ] };
      key <AD03> { [ e, U025B, E ] };
      key <AD04> { [ r, , R ] };
      key <AD05> { [ t, U1D1B, T ] };

      Feels like I’m zeroing in on my problem!



    65. Jedd Schrock (Tue Jul 28, 2020 (19:13:00)) [PermLink]:

      It works!

      I went into my layout file in ../xkb../rules and did some house-cleaning. There were some errant commas without any following unicode values. I also was using tabs in between the commas. I’m not sure which of these changes did the trick, but my keyboard now works.

      This is an example of the syntax in my layout file:

      key <AD02> { [ w, U02B7, U028D, W ] };
      key <AD03> { [ e, U025B, E ] };
      key <AD04> { [ r, U025B, R ] };

      So in summary what I’ve learned here: do not use tabs to separate items in the layout file, and make sure there are no empty characters between the delimiting commas.

      • (not ok)
        key <AD02> { [ w, U02B7, U028D, , W, ] };

      thank you for all your help


    66. Jedd Schrock (Tue Jul 28, 2020 (19:19:07)) [PermLink]:

      I think it would be helpful to list somewhere in these instructions appropriate character names to use in the layout file. My experience tells me that “U0301” style (Unicode) naming always works. From other examples I have seen, it appears other users prefer to use names like “exclam” “period” etc. I think it would be helpful to let new users know what acceptable nomenclature is for the layout file.

    67. Coby (Sun Oct 11, 2020 (14:42:17)) [PermLink]:

      I tried and tried to get this to work, to no avail. I even emailed Dan. But then I went back and looked at my files, and I found several errors.

      1) At first I thought it was because I was using a lot of dead keys and combining diacritics. That turned out not to matter.
      2) I had tried putting my keyboard in its own file. Then I tried making it part of the default file, in my case, US. But it never worked. Then I moved it back out into its own file, because that was the one place I knew for sure evdev.xml knew where to find it.
      3) I had a malformed line. I had forgot to put “default partial alphanumeric_keys” at the top. That shall not happen to you.
      4) I found that it helped to snitch a line from some of the other partial keyboards, ‘include “level3(ralt_switch)” ‘ This goes at the end of the key definitions, indented several steps for clarity.
      5) I did have to do a full restart before my changes showed up.

      I am a baker and I ought to know better than to make more than one modification to a recipe at once. But I combined several, and so I can’t tell you which of them was causing my diacritics not to appear. But no matter. You have to do them all anyway.

    68. Dan (Sun Oct 11, 2020 (18:48:06)) [PermLink]:

      That’s interesting about the level3(ralt_switch). I’ll have to look into that more.

    69. Myke (Thu Mar 4, 2021 (13:13:17)) [PermLink]:

      Good Afternoon

      Great work, here, although I must say: we linuxers seem to reinvent the wheel over and over and over and… you get the idea. No centralized place to find/add solutions… but I digress from my purpose.

      I have noticed that many of the standard keyboards integrate the ‘level3(ralt_switch)’ directly from the ‘level3’ package, without the ‘euro’ component. Would that work for you as well?

      — cheers

    70. Myke (Thu Mar 4, 2021 (13:20:17)) [PermLink]:


      Slight correction: other keyboards include the reference within the layout paragraph, at the very end.

      The Italian, for example, has:

      key <LSGT> { [ less, greater,guillemotleft,guillemotright] }; include “level3(ralt_switch)” };

      as the last line in its ‘basic’ paragraph


    71. Daniel O'Donnell (Sun Apr 4, 2021 (12:26:02)) [PermLink]:

      Thanks Myke, for this.

      I confess the whole level three key business has always been a bit of a mystery to me: Sometimes it works, sometimes it doesn’t for a while, and then usually it does again after a while. I’ve never really figured out what setting is controlling it and when I do manage to get it right its through something like the GnomeTweaks GUI.

      Maybe this is the solution. I’ve never really looked at it. Next time I modify my keyboard, I’ll look at testing this.

    72. Mr M McCarthy (Tue Jun 22, 2021 (10:25:17)) [PermLink]:

      Thanks for posting and keeping this article up to date. After reading I stumbled across an X input hackers blog which may be of interest:

    73. CT (Sun Jul 18, 2021 (03:55:46)) [PermLink]:

      Had a need recently to mix and match Devanaagri, IPA and English without constantly switching input methods… this guide fit the bill perfectly.

      Many thanks!

      (Completely off topic, but I’m pretty sure we met and conversed @ a TEI meet.. College Park, ca.2006?)

    74. Benjamin (Tue Jun 6, 2023 (08:42:26)) [PermLink]:

      Do you know if it is possible to insert more than one Unicode character with one keystroke? What I want to do is insert “a” plus the combining macron below (U+0331). I want to do something like this:

      key <AC01> { [ a, A, a + 0×1000331, A + 0×1000331 ] };

      Obviously the plus sign doesn’t work, and I tried several other things to no avail. Maybe it’s impossible, but if it is possible I would like to know how to do it. Thanks!



    Textile help

    Back to content

    Search my site


    Current teaching

    Recent changes to this site


    anglo-saxon studies, caedmon, citation practice, composition, computers, digital humanities, digital pedagogy, grammar, history, moodle, old english, pedagogy, research, students, study tips, teaching, tips, tutorials, unessay, universities

    See all...

    Follow me on Twitter