Skip to content

Instantly share code, notes, and snippets.

@buckleyc
Last active January 1, 2024 06:30
Show Gist options
  • Save buckleyc/ce6f2325d1ff2f6e5ed8742f97491e80 to your computer and use it in GitHub Desktop.
Save buckleyc/ce6f2325d1ff2f6e5ed8742f97491e80 to your computer and use it in GitHub Desktop.
ReMap Keys on MacOS

This article describes how to quickly and easily remap your MacOS keyboard to better suit your needs using only the command line (i.e., without needing to install any additional applications).

TL;DR: Enter the following command in a terminal on your Mac to remap Caps-Lock as Delete, and remap Delete as Escape:

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

But why would you want to do this? A couple of quick examples targeted at writers or developers: If you are using a modern IDE or code editor (versus 'vim' or 'emacs'), then you may wish to map the very convenient but seldom-used Caps-Lock to the oft-used Delete function. Or if you are editing using vim or emacs, then you may wish to map the Caps-Lock to a commonly-used modifier key such as Ctrl. Or maybe you are just a normal person that tends to not type many acronyms or initialisms, and have gotten tired of seeing dust accumulate on that one key. Personally, I write a lot of documents, code, and spreadsheets, so I am eager to reclaim that convenient key for my day-to-day needs.

I tend to use the Delete and Escape actions quite a bit, and have used Caps-Lock only thrice in the past decade, so that big Caps-Lock key is a terrible waste of keyboard real estate. I decided to remap Caps-Lock as Delete, and then map Delete as Escape. (Remapping the Escape key to a physical key, while pulling it back from the Touchbar on my MacBook Pro so that I can get a tactile smack just feels like a nice little win-win to me.)

There are apps you might install to help remap keys (but please be cautious if you go this route). More effectively, one could also install and use the trusted Karabiner-Elements to remap the keyboard. But there is already a command line utility to reassign keys within MacOS, so no additional installs are necessary.

/usr/bin/hidutil

This utility has been around since MacOS 10.12 (Sierra). The only technical bits you will need to know are: the numeric values for the key mappings, and how to use any terminal app on a Mac. (I use kitty and iTerm2, but the already installed Terminal app works, also.) The key mapping values can be found on a few Apple pages including this one.

Please note that the Apple table shows a short hexadecimal value for each key (e.g., "0x2A"), whereas 'hidutil' uses a longer key mapping which starts with "0x7000000"); you will simply append the final two characters onto the user mapping strings. E.g., "0x2A" becomes "0x70000002A".

To remap the (source) Caps-Lock (0x39) as (destination) Delete (0x2A), you will enter the following command in your terminal of choice.

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

To remap the Delete (0x2A) key as Escape (0x29):

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

Now, you should note that each time you execute the 'hidutil' command for "UserKeyMapping", then any older mapping is overwritten. So, to remap multiple keyboard assignments, you will need to include them all in a single declaration. This means you will have to build the list (inside the square brackets) with each assignment (within each interior set of braces), thus adding subsequent "HIDKeyboardModifierMappingSrc" & "HIDKeyboardModifierMappingSrc" entries. For you Python/JS/JSON/etcetera developers, the declaration is a dictionary containing a single list composed of one or more dictionaries each containing a source and destination for each remapping.

So, to remap both Caps-Lock as Delete and Delete as Escape, then use the following (which contains both sets of assignments within a single list):

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

A final caveat: If your computer is rebooted, then the keymapping will revert to the defaults. If you want this key remapping to persist, then you will need to add this remapping as a LaunchAgent (which is beyond the intended scope of this already long post).

Finally, if you want to reset your keyboard to its system defaults, then you can simply submit an empty UserKeyMapping list:

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

For key mapping information and further details from Apple itself, see this Apple page.

Optional homework: Feel free to implement a remapping ahead of particular apps such that the Caps-Lock key is mapped differently to meet the needs of your primary app ... but this may play rough with your muscle memory.

Update: after writing this post, I found this helpful post by Adam Strzelecki.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment