# Remapping keys on Mac

Published: 22/05/2021
Updated: 22/05/2021


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.

Introduction

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 dettached 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 happend 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 keybord’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 Inpput Source in the System Prefernces. 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 differne 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:

Apple Magic Keyboard ANSI

Can you see this ~ key under the ESC key?

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

Apple Macbook Pro Keyboard ISO

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": [
    {
      "HIDKeyboardModifierMappingSrc":0x7000000E7,
      "HIDKeyboardModifierMappingDst":0x7000000E6
    }
  ]
}

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