< back home

Remapping keys on MacOS Sonoma+

When I switched to the Colemak keyboard layout, I wanted to change the action of my CAPS Lock key to Delete on my macOS. The System Settings do not allow mapping of Modifier Keys beyond a small subset.

hidutil is a command-line utility in macOS that allows users to manipulate the properties of Human Interface Devices (HIDs). One of its most common uses is to remap keyboard keys. This can be particularly useful if you want to customize the keyboard layout or change the behavior of specific keys. The hidutil utility uses a property list (plist) format for its commands. For example, to remap keys, you would use the property --set command followed by a plist specifying the source key (the key to be remapped) and the destination key (the key it should behave as). The keys are identified by their hexadecimal HID usage IDs.

Here’s an example of a hidutil command to remap keys:

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

In this example, the key with the HID usage ID 0x700000035 is being remapped to behave as the key with the HID usage ID 0x700000064. Apple’s Technical Note with key mapping tables can be seen here.

Historically, users have added this command to a shell script like loginscript.sh, which is chmod-ed to run on a restart and retain the key mapping. Or they have relied on third-party packages to manage and daemonize this mapping for them. There is a more straightforward and native way.

hidutil commands can be set to run at every macOS start by creating a plist file in the ~/Library/LaunchAgents directory.

You can generate your own file using this nifty tool developed by amarsyla, which I have deployed for permanence.

Once you generate your desired mappings, paste the output into ~/Library/LaunchAgents/com.local.KeyRemapping.plist

The hidutil command will appear in your background task list under System Settings > General > Login Items. Don’t forget to reset Modifier Key mappings to their default values under System Settings > Keyboard > Keyboard Shortcuts > Modifier Keys if you ever changed them.