How to Use the macOS hidutil Command to Remap Keyboard Keys

When transitioning from a Windows PC to a Mac, the placement of the Command and Option keys can feel entirely unnatural. While macOS provides a basic graphical interface in System Settings to swap modifier keys, it severely lacks the ability to remap standard alphanumeric keys or function rows. To deeply customise your keyboard layout without relying on heavy, third-party kernel extensions like Karabiner-Elements, you can use the built-in macOS Terminal command: hidutil.

Understanding the hidutil Architecture

The hidutil (Human Interface Device Utility) command communicates directly with the macOS input system. It works by intercepting the raw hexadecimal scancode sent by a physical key press and dynamically translating it into a different scancode before the operating system processes it. Because this translation happens at a low level, the remapping applies globally across all applications and bypasses software-specific keyboard shortcuts.

Identifying Key Usage IDs

To use the tool, you must know the specific “Usage ID” (in hexadecimal format) of both the key you want to press and the key you want the system to output. Apple adheres to the standard USB HID specification for these codes. A full list can be found in Apple’s developer documentation, but common IDs include:

• Caps Lock: 0x700000039
• Escape: 0x700000029
• Left Control: 0x7000000E0

Remapping a Single Key

A highly popular modification among developers is remapping the largely useless Caps Lock key to act as a secondary Escape key. To achieve this, you construct a JSON payload mapping the Caps Lock ID (the source) to the Escape ID (the destination).

1. Open the Terminal application.
2. Type the following command carefully (or copy and paste it):

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

3. Press Enter.

The change is instantaneous. The moment you execute the command, pressing the physical Caps Lock key on your keyboard will trigger an Escape action instead.

Making the Changes Persistent

The primary drawback of the hidutil command is that its mappings are stored in volatile memory. If you restart your Mac, all custom remappings are immediately wiped. To make the changes permanent, you must create a LaunchAgent that executes the command automatically every time you log in.

1. Open your preferred text editor (like nano or TextEdit) and create a new XML file containing standard macOS launchd property list (plist) syntax.
2. Embed your hidutil JSON payload inside the ProgramArguments array of the plist.
3. Save the file to ~/Library/LaunchAgents/com.custom.keyboard.plist.
4. Load the agent into the system by running:

launchctl load ~/Library/LaunchAgents/com.custom.keyboard.plist

Your custom keyboard layout will now persist across all reboots.

Resetting the Keyboard Layout

If you make a mistake and map a key incorrectly (for example, mapping the Spacebar to the Delete key), you can instantly reset all custom mappings back to the factory default.

Simply run the command with an empty JSON array:

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

This flushes the active translation table and restores normal keyboard functionality immediately.