Remapping keys on macOS

Did you know you can customize your keyboard on macOS by remapping keys to perform different functions?

In this post, I’ll share how I’ve configured two key mappings that have made a big difference for me:

Mapping Caps Lock to ESC
Remapping the plus-minus (±) key to tilde (~)

Caps Lock to ESC

I never use caps-lock. I just not need it. Unfortunately, it’s really close to shift, tab and other frequently used keys, so every now and then I pressed it by accident.

I remap it to the Escape key because:

If I press it accidentally, there is usually no effect.
When using Vim, the Escape key is used very frequently, but its original location is hard to reach. Making Caps-Lock work as Escape makes it much more ergonomic.

Fortunately, macOS makes it easy to remap the Caps Lock key through System Preferences:

Go to System Preferences > Keyboard > Keyboard Shortcuts > Modifier Keys
Find the dropdown menu for Caps Lock and select “Escape” from the options

Plus-minus (±) to tilde (~)

My MacBook has an ISO keyboard layout, but I prefer the ANSI layout where the tilde (~) key is positioned to the left of the “1” key. Unfortunately, I only realized this preference after purchasing the laptop.

This mapping allows me to use the plus-minus (±) key (located in the top-left corner of ISO keyboards) as a tilde (~) key, effectively mimicking the ANSI layout I prefer.

Option 1: Using Karabiner-Elements

The simplest solution is to use Karabiner-Elements, a powerful keyboard customization app for macOS.

Karabiner-Elements offers a “Change a key to another key” feature that makes this remapping straightforward.

While Karabiner-Elements is an excellent tool, I felt to be a too heavy tool for such a simple remapping.

Option 2: A temporary command-line solution

It turns out that you don’t need any custom software besides the command-line access. While not difficult, this method has some important considerations.

To create a key mapping that lasts until the next reboot, use the following command in Terminal.app:

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

Important notes:

Use Terminal.app rather than iTerm2, as Terminal properly shows the permissions prompt
The first time you run this command, you’ll see a permissions request:

The key codes in the command (like 0x700000035) represent specific keys on your keyboard. You can find the complete list of key codes in Apple’s developer documentation.

To remove the mapping and return to default behavior, run:

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

The main limitation of this approach is that the mapping only persists until you restart your computer.

Option 3: A persistent command-line solution

To create a key mapping that persists across reboots, we’ll complement Option 2 with LaunchDaemon that would run the command automatically at startup.

Step 1: Grant permissions to hidutil

First, you need to give the hidutil command permission to monitor input:

Open System Preferences > Privacy and Security > Input Monitoring
Click the ”+” button to add a new application
Press Cmd + Shift + G to open the “Go to folder” dialog
Enter /usr/bin/hidutil and click Open
Make sure the toggle next to hidutil is turned on

Screen with apps with Input Monitoring permission

Step 2: Create a LaunchDaemon configuration file

Create a configuration file that will run the key mapping command at startup:

sudo bash -c 'cat > /Library/LaunchDaemons/org.example.tildeKeyMapping.plist << EOF
<?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>org.example.tildeKeyMapping</string>
    <key>ProgramArguments</key>
    <array>
      <string>/usr/bin/hidutil</string>
      <string>property</string>
      <string>--set</string>
      <string>{
        "UserKeyMapping": [
            {
              "HIDKeyboardModifierMappingSrc": 0x700000064,
              "HIDKeyboardModifierMappingDst": 0x700000035
            }
        ]
      }</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
  </dict>
</plist>
EOF'

Tip: If you need to map different keys, you can generate the XML more easily using this online tool: hidutil-generator.netlify.app

Step 3: Set permissions and enable the LaunchDaemon

Set the proper permissions for the configuration file:

sudo chmod 755 /Library/LaunchDaemons/org.example.tildeKeyMapping.plist

Enable the LaunchDaemon to run at startup:

sudo launchctl bootstrap system /Library/LaunchDaemons/org.example.tildeKeyMapping.plist

Step 4: Test your configuration

Restart your Macbook and verify that the plus-minus key now functions as the tilde key.