Remapping the Caps Lock key to Escape in macOS Sierra

Update: As of macOS Sierra 10.12.1, the Caps Lock -> Escape remapping can be done natively in the Keyboard System Preferences pane! To remap without any 3rd party software, do the following:

  1. Open System Preferences and click on 'Keyboard'
  2. Click on 'Modifier Keys...'
  3. For 'Caps Lock (⇪) Key', choose '⎋ Escape'
  4. Click 'OK'

(See screenshot for reference).

For the past three years, I've used the Mac Development Ansible Playbook to automatically configure all my Macs, so they have the same applications, utilities, and preferences at all times. One of the most important tweaks I use is the combination of Karabiner and Seil to remap a few keys and to increase the key repeat rate.

Unfortunately, these extensions are not yet working in macOS Sierra, but the people behind the project have crafted a simple utility for the interim, Karabiner Elements, which doesn't yet have a UI and isn't in Homebrew's Caskroom (so I can't automate the setup), but it at least allows key remapping via a JSON configuration file.

For my purposes, I can live without the blazing-fast key repeat rate (right now it's slower than I'm used to, but faster than you can set via the System Preferences configuration), but I can't live without my Caps Lock-as-Escape remapping (muscle memory + Vim mean the teensy tiny Esc key is out of the question!). So here's how I set up Karabiner Elements to remap the key:

  1. Download Karabiner Elements.
  2. Expand the image, and run the installer.
  3. Restart your Mac.
  4. Open Karabiner Elements, go to the 'Misc' tab, and click 'Check for updates' (this is important—if you don't have the latest version, the remapping probably won't work correctly and you'll end up with no escape key! I had to update to 0.90.39 as of this writing).
  5. If there was an update, install it, then restart your Mac again.
  6. Open Karabiner Elements again, and follow the instructions under 'Simple Modifications' to create a remap file at ~/.config/karabiner/karabiner.json.
  7. Open the file and put the following content into the file to define the remapping:
{
    "profiles": [
        {
            "name": "Default profile",
            "selected": true,
            "simple_modifications": {
                "caps_lock": "escape"
            }
        }
    ]
}

After saving the file, your Caps Lock key should start working as Escape; if not, restart your Mac once more, and then it should be working. You can test key presses using the Karabiner-EventViewer app that's included with Elements.

Further reading

karabiner
seil
macos
sierra
escape
caps lock
vim
keyboard

Comments

I guess I shouldn't have updated, but I didn't realize Karabiner was broken on Sierra. I've been using a 60% keyboard with caps lock remapped to control and control+hjkl as arrow keys for years. I can remap caps lock, but there is literally nothing to help me get my arrow keys back. I don't think they plan on adding multiple key bindings to "Karabiner Elements" either. Sad day.

Thank you for the instruction. Could you advise how the json map should look like if I want to remap Caps Lock to a F19 key? As I understand there must be something instead of "escape" value in the provided map. But what?

Try the following:

{
  "profiles": [
    {
      "name": "Default profile",
      "selected": true,
      "simple_modifications": {
        "caps_lock": "f19"
      }
    }
  ]
}

See this and many other examples in the Karabiner-Elements examples.

Just wanted to say thank you for posting this. I use the same setup you do and you just made my development life a lot easier.

Thank you. Was the one thing after the upgrade that wasn't working for me.

Could you advise how the json map should look like if I want to remap 'return to a right_shift key?

Just wanted to say thanks for sharing! It's incredibly hard to use a keyboard once you've remapped it and then your mappings are gone.

It actually appears that you will be able to remap Caps Lock to Escape natively with OS 10.12.1.

I've heard this from a couple different people—if that's the case I'll be able to live without Karabiner entirely! We'll see (I'm not one to run the beta for now...).

I'm using 10.21.0 and this isn't working. I created the file exactly as you indicated.

I'm not sure what you mean by "follow the instructions under 'Simple Modifications'" however

Any idea what the name for the Fn key is? I want to swap it with the Left Command, but both 'fn' and 'function' didn't work.

In the meantime, I swapped the Caps Lock with the Left Command, so that's working but if anyone knows the name for the 'fn' key, that'd be great.

Would it be possible to make alt plus the a key type 1 and do the same with all the home row keys (such as alt plus the s key type 2 and so forth)?

Thank you so much for posting this! I found karabiner's github and tried to set it up, but couldn't get the package to compile. The link you posted has the entire package with the auto installer.

I was able to swap "CAPS LOCK" with "Escape" key using the instructions you've posted above and modifying the values accordingly.

Thanks man I just had my update last night and the backspace not working thing with Seil really drove me crazy.

Thanks to you, I can now successfully use capslock to open Spotlight. Thanks you! ?

Its awesome !! I was looking for this after updating to sierra and got Caps -> Esc. Thanks a lot.

Do you know of a way to have the same "ignore Apple internal keyboards" setting that normal Karabiner had?

With Karabiner/Seil on OSX, I was able to have CapsLock mapped to ESC for a solo press, but Left-CTL if I pressed it in combination with another key. Do you know any possible way to do this on Sierra? I really like having my tmux and vim "magic" key be the same.

Jess, I started using karabiner-elements after getting a new Macbook with Sierra. You might check that out. I was using Karabiner/Seil prior to this and didn't even know the multiple bindings for the same key was possible.

If you find a way in karabiner-elements could you please post it here?

How can I remap the Help key on my mac keyboard to B...the old karabiner allowed me to do this within that xml file they allowed users to alter.

With elements it seems the only “help” key they offer is under PC keyboard category.

When attempting to map that PC help to B it didn’t work.

How can I get it to recognize the mac Help button, so I can map it to B?

Any help is appreciated.

As a Vim user since I bought my Amiga a bazillion years ago, and now that I have a brand new MacBook Pro...

THANK YOU!

Apple makes nice computers, and I love Unix. But, damn, they make crappy keyboards and mice. Beautiful, but not functional.

Hey, but after the swap, the ESC key does not become Caplock, it keeps the same ESC behavior. I just using the map in the system preferences