I have a custom keyboard layout located in /usr/share/X11/xkb/symbols/us. Every time an update happens, this file is updated to the standard keyboard layout. Is there either a way to change this permanently, or a way to change this in userspace away from distro-level config?

If there is a better way to approach custom keyboard layouts, please let me know. As far as I am aware, the best way to approach this is with xkb symbols files, and there is not much documentaion for these.


  • Which Linux distribution are you using? Debian-based distributions (using dpkg) have a concept of divert which allow you to tell them not to override a custom file of yours... – filbranden Mar 3 at 22:51
  • That's why you don't modify existing layouts, but instead you make your own layout based on an existing layout, copying and modifying files as necessary. – dirkt Mar 5 at 8:07
  • 1
    @filbranden: debian has bitten me with this before, so it could be debian/ubuntu. – Wyatt8740 Mar 14 at 1:25
  • 1
    @dirkt: an explanation for someone who isn't familiar with where custom layouts are stored or how they are loaded would be appreciated. I've seen this advice before but never a "for dummies" guide. – Wyatt8740 Mar 14 at 1:26
  • @Wyatt8740: There's no for dummies guide because the whole thing is a bit complex, and depending on what you want to do you may need to copy and modify quite a few files. The best introduction to XKB I know is the Unreliable guide to XKB configuration by Doug Palmer. – dirkt Mar 14 at 6:41

Make a directory tree under /home/<user>/ which has the same structure as /usr/share/X11/xkb/. In other words:

$ tree -L 1
├── compat
├── geometry
├── keycodes
├── rules
├── symbols
└── types

So put the relevant files in compat, symbols, etc. You obviously don’t need to make empty directories, just the directories for the files that you need.

Then consider renaming your symbols file to something different than us. There might be a way to disambiguate your own us symbols file from the one under /usr/share/X11/xkb/, but it is easier to just pick a new name which doesn’t appear in /usr/share/X11/xkb/symbols/. mine will do fine.

Let’s say that you put your custom Xkb directory at /home/<user>/my-xkb and that your custom symbols file is named mine.

If you use setxkbmap(1) to set your layout you simply need to change it to print its output and pipe it to xkbcomp(1). So if this is your setxkbmap invocation:

setxkbmap mine

You will need to change it to this:

setxkbmap mine -print |
    xkbcomp -I"/home/<user>/my-xkb" - "$DISPLAY"

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.