# How do I remap a key in macOS Sierra, e.g., Right Alt to Right Control?

I used to use Karabiner to remap Right Alt to Right Control (as an Emacs user I use Control MUCH more that Alt) but updating to Sierra broke this. Downgrading is not an option.

How do I manually remap keys in Sierra? I specifically would like to remap Right Alt to Right Control.

Apple's Technical Note TN2450 describes how to remap keys. Running the following command will remap Right Alt to be Right Control.

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


Note that the above command is not switching the Right Alt and Right Control. They will both be Right Control. If you have a MacBook, you will not notice this until plugging in an external keyboard. If you want to switch Right Alt and Right Control, you need to add a second switch command, like the following.

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


The table at the bottom of the Technical Note has a list of hex values for each key. To generalize the above answer to switch any keys, you must or the hex value from that list together with 0x700000000. The following Python code demonstrates one way to do this.

In [1]: def convert(val):
...:     int_val = int(val, 16)
...:     int_ref = 0x700000000
...:
...:     return hex(int_ref | int_val)
...:

In [2]: r_alt = '0xE6'

In [3]: print(convert(r_alt))
0x7000000e6

• Nice - thanks! Is there any way to restore the mappings to their defaults with this command? – Aᴄʜᴇʀᴏɴғᴀɪʟ Jul 10 '17 at 21:48
• @Cᴀʟʟᴏᴅᴀᴄɪᴛʏ to reset any key, you simply run the command again with that key's value in both Src and Dst. – Steven C. Howell Jul 11 '17 at 12:38
• This reverts on reboot. I can re-run this command on each boot, but I'd prefer not to do this. Is there a way to make this permanent? – firebush Aug 7 '18 at 14:49
• @firebush This post suggests using a login hook to make commands like this persistent: stackoverflow.com/a/46460200/629530 – firebush Aug 7 '18 at 21:56
• @StevenC.Howell How about combinations of function modifiers? For example, the backward slash \  in my keyboard is Shift+Option+7 which I would like to replace with something simpler such as Option+. which I hardly use. How do I do that? Thanks for your help. – Nanashi No Gombe Oct 8 '18 at 20:12

A more general and user-friendly approach is to use Karabiner-Elements, which is a version of Karabiner that works on Sierra.

• Quick update on Karabiner-Elements. It works on macOS High Sierra 10.13.3 (17D102) I successfully swapped my right Command and Option keys. – Steve Clement Mar 20 '18 at 0:16
• Third party apps are never "more general". Why would anyone clutter their system with apps doings things that are built right into the OS? – Bachsau Jun 23 at 13:14
• @Bachsau it is more general in that allows you to do a lot of other stuff, e.g. setting up key combinations, macros and profiles, or using shared and/or split mapping configurations for any internal and external keyboards. – Janosch Aug 27 at 12:17

I have a new MacBook Pro with a Scandinavian keyboard. This new model no longer has an Esc key, which is a significant handicap for me.

I discovered that the following will translate the § key (upper left, left of 1 and above tab key) - which I don't think I have ever used for anything before today - to produce Esc.

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


In Apple's documentation (linked from Steven's answer) this is labelled as "Keyboard Non-US \ and |" (0x64).

Several of the "non-US" keys are hard to discover because they typically refer to keys which have a different label on the keyboard you are using. (I also discovered that "Grave accent and tilde" refers to the key between left shift and z, which on my keyboard produces <. I was unable to establish which key corresponds to "Non-US # and ~" and did not experiment further once I found my key.) If you want to experiment, try running the script in the terminal until you find the key you need:

for ((i=1;i<=128;++i)); do
printf '0x7000000%0x\n' "$i" printf '{"UserKeyMapping":[{"HIDKeyboardModifierMappingSrc":0x7000000%0x,"HIDKeyboardModifierMappingDst":0x70000000a}]}' "$i" |
xargs -0 hidutil property --set >/dev/null
read -p "Type some stuff: "
hidutil property --set '{"UserKeyMapping":[{}]}' >/dev/null
done


This loops over the keycodes and changes one at a time, in the hope that you can find through trial and error a key which is not particularly useful for you. Try typing something when it asks you to -- if you get a g instead of what you expected, you have found the right key code. (Change 0x70000000a to something else if g is not a convenient choice for you. Maybe you want to remap the g key?) When you are done typing, just hit Enter to proceed to the next key.

For what it's worth, the last command inside the loop is how you zap all UserKeyMapping settings:

hidutil property --set '{"UserKeyMapping":[{}]}'


When you initially run hidutil property --get UserKeyMapping it produces

(null)


but it seems you cannot feed back this value to zap the setting (or rather, it accepts but ignores this input).

(If you are unfamiliar with the Terminal, just copy/paste the thing from for until done at your bash$ prompt or similar.) As per this related Stack Overflow question you can put the command in a script file in your home directory and add it to your launchd configuration to make this change persistent. In case some readers are not comfortable doing this on their own, here's a quick script which does this for you. Again, just copy/paste this at the Terminal prompt. mkdir -p "$HOME"/bin
printf '%s\n' '#!/bin/sh' \
'hidutil property --set '{"UserKeyMapping":[{"HIDKeyboardModifierMappingSrc":0x700000064,"HIDKeyboardModifierMappingDst":0x700000029}]}' \
>"$HOME"/bin/userkeymapping chmod 755 "$HOME"/bin/userkeymapping
cat<<: >"$HOME"/Library/LaunchAgents/userkeymapping.plist <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key> <string>userkeymapping</string> <key>ProgramArguments</key> <array> <string>$HOME/bin/userkeymapping</string>
</array>
<true/>
</dict>
</plist>
:
launchctl load "$HOME"/Library/LaunchAgents/userkeymapping.plist  Obviously if you ended up with some other key than 0x700000064 you need to change that in the script, or in the file "$HOME"/bin/userkeymapping it ends up creating if you already ran the above.

• An earlier version of this answer advocated using LoginHook but it wasn't working for me, and based on stackoverflow.com/a/22872222/874188 I switched to a launchd approach instead. – tripleee Feb 27 at 6:58
• As an ardent vi/vim fan this is precisely what I was looking for. Thank you. – Philip Kearns Apr 14 at 17:57

# If all you want to do is remap a single key

### Example: How to Remap Escape Key on Mac

1. Go to the  Apple menu and choose “System Preferences” and then go to the “Keyboard” preference panel and choose the “Keyboard” tab

2. Click on the “Modifier Keys” button in the lower right corner

3. Choose the key you want to remap and modify to perform the Escape function: Caps Lock (our recommendation), Control, Option, or Command
4. Select “Escape” from the dropdown list corresponding to the key you want to remap as a hardware Escape key then click “OK” to set the change

reference

• This only gives you control over the four keys which are enumerated in this answer. – tripleee May 15 at 5:06
• Correct, and very helpful. If someone wants to remap additional keys consider karabiner – jasonleonhard May 15 at 18:31
• It looks like there's no way to specify a specific key, like "right ⌥", either. The most specific you can get is the signal, as in "any ⌥". – Merchako May 16 at 16:15
• Correct, but the good part is you don't have to install anything it just works. – jasonleonhard May 16 at 23:19

In case that you might want to restore the defaults:

# setting it to 'null' does not work on my MBP High Sierra
hidutil property --set '{"UserKeyMapping":[]}'