Sway uses Wayland, so any XKB files will be parsed by Sway, not X.

  • I want to add a layer on the keyboard (probably using Hyper)
  • I want to shuffle some modifier keys around

I've looked at a lot of sites, but I still don't know how to accomplish this. There are so many parts to XKB, and I'm not sure what goes where. I want an example file (or files) and an explanation.

2 Answers 2


Let's say your xkb configuration file is named custom-xkb, and is stored in ~/.config. Then you include this in your sway configuration file:

input "type:keyboard" {           # or input <identifier> 
  xkb_file ~/.config/xkb/custom-xkb

You probably already know that part -- the hard part is creating the custom-xkb file. I'm no specialist, but here's what I'd do:

  1. I'd do a web search for "xkb specification", and that brings to you all kinds of information, from wikipedia to the x.org's full specification. You probably have a collection of resources like those already.
  2. Then I'd find in my system the default keyboard configuration files, maybe in \etc\X11\xdg\ or something (you may have to look around a bit: in my weird distribution, the path is /nix/store/n1mlvwrkdlm77b4ai9s26kwji89jjb65-xkeyboard-config-2.27/share/X11/xkb/).
  3. In that path, I'd look for two sub-directories: symbols and types. The first is where the key-maps for all the different languages are, and within each file, the key-map variations for that language. The second sub-directory is where the virtual keys are defined (such as Mod1, Control, etc.).
  4. Then I would copy the contents of those files to my ~/.config/xkb/custom-xkb and experiment different edits to see what happens. And try to clear out my doubts using the internet resources I'd have collected. If anything catastrophic happened, I'd hit Control+Alt+F1, then do a nox login, comment the line xkb_file ~/.config/xkb/custom-xkb and restart the X server...
  5. I wouldn't tamper with the contents of the sub-directories rules, geometry and keycodes. But you need to, take a look into those too.

I haven't actually done none of that, but maybe it works. I think that looking at the actual configuration files helps to figure out what the tutorials and guides are actually saying...

Gook luck

  • Notice also that in sway's input {...} structure, there are separate commands to set rules, symbols... Commented Aug 19, 2020 at 19:37

XKB is a really complicated beast indeed. (At least in my experience. It seems to have some weird design decisions which I attribute to the fact that it's first release was way back in 1996, and also not the best documentation in my opinion.)

I have managed to get to some level of understanding by experimenting with lots of different configurations and settled on a subset of functionality that I can reliably guess the behavior of and comfortably create layouts with while still having enough flexibility to express what I'd like to achieve.

Writing a comprehensive tutorial of what I've learned would take quite a bit of time, but what you can do is take a look at my configuration files which are hopefully more digestible than reading the default layouts.


(They are included in my Sway config here.)

I particularly recommend the Lenovo-L13.xkb file, which I've created for my laptop, as it has multiple layers. (I've even turned my space bar into a modifier while held down with evdoublebind.) The Vortex Core layout is also a good one, but that's not the full picture, as the keyboard itself is also programmable.

If you need something that cannot be found here, as the previous answer has already mentioned, the place to start is looking at are the built-in files. You can get an idea of which of them are utilized for your keyboard by using setxkbmap -print. From then on you can look up the imported definitions in wherever your xkb files are located. (Unless you're using NixOS it's probably in some reasonable place, like /usr/share/X11/xkb under Arch.)

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .