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":

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":

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))
  • 1
    @Cᴀʟʟᴏᴅᴀᴄɪᴛʏ to reset any key, you simply run the command again with that key's value in both Src and Dst. Jul 11 '17 at 12:38
  • 1
    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
  • 2
    @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
  • 1
    @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. Oct 8 '18 at 20:12
  • 1
    @StevenC.Howell Unfortunately that list is incomplete. I want to remap the menu key on a windows keyboard to work as a second command key.
    – Bachsau
    Jun 24 '19 at 15:04

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

  • 2
    Quick update on Karabiner-Elements. It works on macOS High Sierra 10.13.3 (17D102) I successfully swapped my right Command and Option keys. 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 '19 at 13:14
  • 2
    @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 '19 at 12:17
  • 1
    @Bachsau I keep different profiles for each of my keyboards, so they function the same. Very nice app
    – AlexG
    Nov 25 '19 at 22:22
  • Fantastic app. Works on Big Sur like a charm. Sep 21 at 20:16

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

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


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 ~/bin
printf '%s\n' '#!/bin/sh' \
    'hidutil property --set '"'"'{"UserKeyMapping":[{"HIDKeyboardModifierMappingSrc":0x700000064,"HIDKeyboardModifierMappingDst":0x700000029}]}'"'" \
chmod 755 ~/bin/userkeymapping
mkdir -p ~/Library/LaunchAgents
cat<<: >~/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">
launchctl load ~/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 ~/bin/userkeymapping it ends up creating if you already ran the above.

  • 1
    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 '19 at 6:58
  • 1
    As an ardent vi/vim fan this is precisely what I was looking for. Thank you. Apr 14 '19 at 17:57
  • I believe this should work with zsh too, but remain baffled that Apple switched to this wicked shell as the default for new users.
    – tripleee
    Apr 16 at 11:04

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


  • 6
    This only gives you control over the four keys which are enumerated in this answer.
    – tripleee
    May 15 '19 at 5:06
  • Correct, and very helpful. If someone wants to remap additional keys consider karabiner May 15 '19 at 18:31
  • 1
    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 '19 at 16:15
  • 1
    Correct, but the good part is you don't have to install anything it just works. May 16 '19 at 23:19

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .