Remapping keys on Mac

Photo by Brandon Romanchuk / Unsplash

TLDR: This short blog post is about remapping keys on Apple Mac OS. Might be especially useful if you have both ISO and ANSI keyboards and want to remap keys to make your keyboard experience more consistent.


I own a Macbook Pro model 2017 and I am pretty happy with the device, The only thing that really makes me sad is the keyboard. The keyboard is just a piece of shit. It is probably the worst keyboard I ever had: it makes very weird tactile experience, every key has its own sound, it is too much sensitive to even a smallest dust particle. And after around 3 years it got broken: several of the keycaps just got detached from their keys, one button started making double clicks, another button started skipping clicks, etc. It is just a pure disaster. What is interesting is that I still own a Macbook Pro model 2012 and it is still in perfect condition, and its keyboard still works perfectly.

And it that happened this year that I received Apple Magic Keyboard as a gift. At first, it felt a bit weird (I never had one before). But just in a couple of days I fell in love with this device. It feels like a very good assembled device, the tactile feels are very good, it has good tactile feedback, it clicks but the sound is not annoying. Overall, it is a very good device as for me.

The problem

But then the other thing popped up: the Macbook keyboard is in the ISO layout and the Magic keyboard's layout is ANSI. If you have no idea what all these keyboard layouts mean, you can refer to this article on the difference between ISO and ANSI keyboard layouts.

Personally, I prefer ANSI layout (mostly used in the USA) to the ISO layout (that is mostly used in Europe). For me, the most annoying things in the ISO layout are:

  • short Left Shift key
  • an additional key between the Left Shift and the Z keys
  • the Paragraph key under the ESC key
  • short Enter key

Although, all these issues can be (more or less) mitigated by changing the Keyboard Input Source in the System Preferences. So, I had been working on the Macbook keyboard for a while with no severe discomfort.

But when it came to the Magic Keyboard, I realized that I have a new kind of an issue: it was impossible to have same layout on both devices (Macbook keyboard and Magic Keyboard). In particular, I really often use the 'CMD - TAB' combination for switching between applications, and also 'CMD - ~' combination for switching between windows of the same application. And since the '~' key has different place in ISO and ANSI layout, the 'CMD - ~' combination worked either on the Macbook keyboard or on the Magic keyboard, but I was unable to make it work on both devices simultaneously.

This is how the relevant part of the Magic Keyboard looks like:

Can you see this '~' key under the ESC key?

And this is how the same part of the Macbook Pro keyboard looks like:

As you can see on the latter picture, under the ESC key there is totally different key - a 'paragraph' key, and the '~' key is placed between the Left Shift key and the 'Z' key.

So, when I wanted to use 'CMD - ~' combination to switch between windows of an application, I had to use different physical keys on Macbook and Magic keyboard. And this had been making me mad.

The solution

Hence, I needed a good way to remap Macbook keyboard so the 'paragraph' key would work as the '~' key. Then, suddenly this article (in Russian) popped up from my twitter feed. The article was about exactly the same idea I was thinking about. Initially, the author used Karabiner for remapping keys, but then he faced with various kind of issues and found out that there is a pretty native way in Mac OS for remapping keys. If you want more details, please refer to that article.

Now, how I solved my issue after I read the article. Mac OS has standard utility `hidutil`. This utility can be used to control input devices, - in particular, to remap keys.

If you run it as this: hidutil property --get "UserKeyMapping", it will show you key remaps that are currently known to the system. By default, there are no remaps, so you will probably see nothing in the output.

Now, to remap a key you should run this utility passing some JSON structure to it. The JSON structure should contain codes of the keys you want to remap.

For example, this structure being passed to hidutil utility will remap Right Cmd to Right Alt (the example is taken from the article I refer to above):

  "UserKeyMapping": [

Now where you can find the key codes? I found two good places in the Internet to refer to: Technical Note TN2450 from Apple Developer Library and scancodes page on Deskthority Wiki.

Now back to my case again. According to the web pages above, the 'paragraph' physical key has scan code 0x64 and the '~' physical key has scan code 0x35. So, the proper command for remapping 'paragraph' to '~' would be this one:

hidutil property --set '{ "UserKeyMapping": [ { "HIDKeyboardModifierMappingSrc": 0x700000064, "HIDKeyboardModifierMappingDst": 0x700000035 } ] }'

Voila, it works! Now I can use same physical keys combination for both Macbook Pro keyboard and Magic Keyboard. The only thing is that `hidutil` does not save the changes, so they will be lost after reboot. There are couple of ways of persisting these changes, but I stopped with this one:

  • put the command into a shell script under the user home directory
  • open the `Users & Groups` dialog, find the user, add the shell script to the list of the `Login Items`
Andrii Serhiienko

Andrii Serhiienko

Sweden, Stockholm