I use Linux on a Macbook with a UK/GB keyboard and I customize the keymap to solve some problems Apple's weird keyboard layout causes. I use xmodmap to do this. I'd like to try Wayland, but xmodmap doesn't work in that. How can I achieve a similar result in Wayland? The .Xmodmap file I use contains the following:

keycode  12 = 3 numbersign 3 sterling sterling sterling threesuperior sterling
clear Control
clear Mod4
add Control = Control_L Super_R
add Mod4 = Super_L
keysym Caps_Lock = NoSymbol Caps_Lock

Line 1: On UK keyboards Shift-3 is £, so # usually has its own key near Return. But on the Mac # is obtained with Altgr-3. As a programmer I use # far more than £ so this line swaps them over. Selecting US layout also achieves this, but doing that in Linux also swaps some other commonly used keys, whereas in OS X those other keys are unaffected by US/UK.

Lines 2-5: Make the right Cmd key act as Right-Ctrl, because this keyboard has no physical right Ctrl key.

Line 6: Makes CapsLock only work if you press it with Shift. Not Mac-specific, this should be a standard option for all OSs and keyboards.

  • I'm partway there: apparently Wayland uses xkb, and xmodmap is deprecated in X anyway. Unfortunately xkb is considerably more complicated, and GNOME never considered that users might need to customise it, so I've raised a second question.
    – realh
    Jul 6, 2016 at 19:20

5 Answers 5


Unfortunately modifying the system XKB database in /usr/share/X11/xkb is the only way; from your other question it looks like you've gotten that part working.

The limitation is mostly due to the immaturity of Wayland and a design oversight in XKB.

  • Tools like setxkbmap and xkbcomp provide an -I option to add a user-defined database to search (eg ~/.xkb or ~/.config/xkb, with files and subdirectories laid out like the system database). These tools interact with the X server, so they might be useful configuring the Xwayland compatibility layer for running X applications under Wayland. But they do not at present speak the Wayland protocols.

  • Wayland protocols are still maturing. Currently it seems the input-method and text-input protocols are most relevant, and both are unstable. Neither mention anything about altering a defined keymap; these details are left to the compositor.

  • GNOME and KDE both provide keyboard-handling settings daemons that should handle system XKB options, including changing on the fly. To the best of my knowledge, there's no way to tell either about user customizations. As far as I know, Weston and other compositors rely on config files or environment variables to set XKB options at startup, and provide no way to change them other than exiting and restarting.

  • Even in XKB itself, this is not fully supported. Your custom symbols file can include other system symbols files. But at present there's no include functionality for XKB rules files, so even if you had a tool that would talk to the Wayland compositor and would look up your personal customizations, you'd have to manually include all the rules you want to use (ie copy rules/evdev* from the system XKB and modify it). libxkbcommon has an open issue on this topic and a related bug.

  • 1
    I should have made it clearer that I've pretty much solved this now. I said so in the other question, but the information is a bit disjointed. I'm intending to document this more clearly when I get around to adding a blog to my website, then I'll have to remember to link to it here.
    – realh
    Apr 2, 2017 at 18:35
  • sure, but it was still an unanswered question, so i tried to address the Wayland-equivalent-of-.Xmodmap aspect.
    – quixotic
    Apr 2, 2017 at 19:30
  • 4
    I've now documented this in detail in a blog post.
    – realh
    May 16, 2017 at 21:07
  • 1
    Do you find there have been any improvements or overhauls to this matter in GNOME to date?
    – Matan
    May 16, 2021 at 15:16
  • Speaking of tools, would this one work? github.com/snyball/Hawck
    – Chaas
    Apr 5 at 13:39

I've been using Interception Tools for Linux with success for this, and know of people producing other plugins for their custom mappings too. caps2esc is a first proof-of-concept plugin that I use everyday, and works both on X and Wayland. The tool is a bit lower level than usual mapping software, but quite flexible, and my plan for a next plugin is a generalized chording mapping tool.

Disclaimer: I'm the author.

  • The Interception Tools look really interesting! Thanks for your work!
    – balu
    Oct 7, 2018 at 4:11
  • 2
    Not sure how I feel about running all my keyboard input through a python script
    – Ace.C
    Sep 18, 2019 at 18:57
  • Python? Interception Tools is written in C and C++
    – nickspoon
    Feb 20, 2020 at 1:11

For those coming here in 2018 (Ubuntu 17.10), the most critical part of this can be accomplished using the GNOME Tweak Tool.

Gnome Tweak Tool > Keyboard & Mouse > Additional Layout Options > Ctrl is mapped to Win keys (and the usual Ctrl keys).

  • 3
    Does using "Gnome Tweak Tool" (whatever that is) sets the new mappings for other windows managers/environments/graphical shells, too? May 16, 2018 at 7:40
  • Gnome Tweak Tool cannot remap Caps Lock.
    – andyn
    Nov 20, 2018 at 9:20
  • @andyn my gnome-tweaks-3.34.0-1.fc31.noarch can remap Caps Lock - e.g. 'Caps Lock is also a Ctrl', 'Make caps Lock an additional Esc', 'Caps Lock as Ctrl' and many more. Nov 23, 2019 at 12:07

This answer has the same idea as quickotic's answer but just with a more detailed example:

Gnome Tweaks have a list of 20 or 30 keyboard tweaks you can do via xkb. Sometime you can find the tweak you're looking for by default. In my case, I wanted to swap printscreen key with Menu.

The only option to modify the printscr key available via xkb was to replace it with Win_R. Gunnar Hjalmarsson on this thread suggested to me that I modify xkb's modifications so that the printscr/win_r would do printscr/menu instead. We worked out a solution together and I'm going to retransmit it here:

In terminal, enter:

sudo su
nano /usr/share/X11/xkb/symbols/altwin

At the bottom of the file you will find:

// Win is mapped to the PrtSc key (and the usual Win key).
partial modifier_keys
xkb_symbols "prtsc_rwin" {
    replace key <PRSC> { [ Super_R, Super_R ] };
    modifier_map Mod4 { <PRSC>, <RWIN> };

Delete this section and replace it with this:

// Menu is mapped to the PrtSc key (and the usual Win key).
xkb_symbols "prtsc_rwin" {
     replace key <PRSC> { [ Menu, Menu ] };
     modifier_map Mod4 { <PRSC>, <MENU> };

To delete in nano, use backspace key (highlighting and deleting doesn't work). To paste, use shift-ctrl-v. To exit and save, press ctrl-x, select yes to overwrite and press enter.

Reboot. In Gnome/Ubuntu Go to gnome-tweak-tools In tweak tools go to Keyboard & Mouse section, press the Additional Layout Options button and expand Alt/Win key behavior. Selecting the option on the very bottom: Win is mapped to printscr (remember that we've modified just this behavior to swap print and Menu instead of print and Win). (I'm sure there is a way of turning on the modded xkb option in KDE but I don't use it, so I can't give you the exact procedure).


The top answer in addition to https://unix.stackexchange.com/a/215062 is very helpful, but it is not necessary to edit the system xkb files.

https://xkbcommon.org/doc/current/md_doc_user_configuration.html helpfully says you can put the symbol file in $XDG_CONFIG_HOME/xkb/symbols/<name> and custom rules in $XDG_CONFIG_HOME/xkb/rules/evdev

I could then in sway easily load my custom symbol file.

So for a full example, where I added åäö to US dvorak:

xkb_symbols "sweletters" {
    //å on alt+u (qwerty f)
    key <AC04> { [     u,   U, aring,       Aring           ]   };
    //ä on alt+e (qwerty d)
    key <AC03> { [     e,   E, adiaeresis,  Adiaeresis      ]   };
    //ö on alt+o (qwerty s)
    key <AC02> { [     o,   O, odiaeresis,  Odiaeresis      ]   };
    // make right alt altGr
    include "level3(ralt_switch)"


! option = symbols
  swedish_letters_on_dvorak:sweletters    = +swedish_letters_on_dvorak(sweletters)
! include %S/evdev

(and in my sway config)

input type:keyboard {
    xkb_layout "us"
    xkb_variant "dvorak"
    xkb_options "caps:escape,swedish_letters_on_dvorak:sweletters"
  • 1
    Thanks @h33925, that's useful to know. I was going to ask you about evdev.xml, but the answer to my question is in the link you provided.
    – realh
    Apr 6 at 13:22

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.