Apple - How do I remap a key in macOS Sierra, e.g., 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

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


This is an addendum to Steven C. Howell's answer.

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>
    <key>RunAtLoad</key>
    <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.

Tags:

Macos

Keyboard

Keybindings

Recent Posts