A Key Remapper on a Mac: Moving the Keys You Actually Press

Searching for a key remapper on a Mac usually follows a specific irritation. Caps Lock is in the best position on the keyboard and does the least useful job. An external keyboard built for Windows puts Alt where Command should be. A key that was pressed forty times an hour on the last machine now sits under a different finger. The fix looks like it should take two minutes, and for one of those cases it does. For the others, the answer sits in a different layer of the system, and knowing which layer applies saves an afternoon of installing things.

There are three routes on macOS, and they do not overlap as much as the search results suggest. One is a settings pane that ships with the system. One is a command line tool Apple documents for exactly this purpose. One is third party software that sits underneath both. What follows is where each one stops.

The pane that ships with macOS

Apple's own route covers the modifier keys, and it is the only route most people need.

Open the Apple menu, choose System Settings, click Keyboard in the sidebar, then click Keyboard Shortcuts. Select Modifier Keys in the sidebar of the panel that opens. Each modifier has a pop-up menu next to it, and each menu can be set to the action of a different modifier or to No Action. Apple's documentation uses the obvious example: someone accustomed to a keyboard with Control where Caps Lock sits on an Apple keyboard can open the Caps Lock pop-up menu and choose Control, and the Control action happens on every press from then on. A Restore Defaults button puts everything back.

Two details in that pane matter more than the pane itself. The first is No Action, which is the quiet answer to a key that causes more trouble than it solves. Caps Lock set to No Action stops the accidental block capitals without adding anything to learn. The second is that the choice is made against a keyboard. A Mac with a built-in keyboard and an external one attached is two sets of hardware, and the swap that makes the external board usable should not follow to the laptop keys.

This pane handles modifiers and nothing else. There is no row for the letter keys, no row for Return, and no way to make one key type something different. If the goal is to move Command to where Alt is on a PC keyboard, the work is finished here. If the goal is to make the key to the left of A behave like Escape, it is not.

hidutil, and why the change disappears

Apple documents a second route for the cases the pane cannot reach. In macOS Sierra 10.12 the mechanism for key remapping changed, and Technical Note TN2450 describes what replaced it. The part that matters outside of software development is the hidutil command line tool.

A remapping is expressed as a list of source and destination pairs, with the property names HIDKeyboardModifierMappingSrc and HIDKeyboardModifierMappingDst. Each key is a hexadecimal value made by combining 0x700000000 with the keyboard usage value for that key, and the technical note carries the full usage table. Apple's own example swaps the A key and the B key by setting two pairs in one command. The current state can be read back with hidutil property --get "UserKeyMapping", and a null result means no remapping is active.

Three lines in that document decide whether this route is usable. No special privileges are required, so nothing needs to be unlocked or authorised. The scope applies to all users of the machine, not to the account that ran the command. And the remappings are lost when the system is restarted, or when the keyboard service is removed, which includes the moment the last keyboard is disconnected.

That last line is the whole catch. A hidutil command is a change to the running system, not a setting. Making it survive a restart means arranging for it to run again at login, which is a launch agent and a property list file, and at that point the amount of work has passed what most people signed up for. As a way to test a mapping for ten minutes before committing to it, it is excellent. As the permanent home for a mapping that gets pressed every day, it needs scaffolding.

Karabiner-Elements, and what a real remapping layer buys

The third route is Karabiner-Elements, which sits at the same level as the system's own handling of the keyboard rather than on top of it.

Its site describes it as a keyboard customizer for macOS and offers the current release, version 16.3.0, with separate builds listed for macOS 27 Golden Gate, macOS 26 Tahoe, macOS 15 Sequoia, macOS 14 Sonoma and macOS 13 Ventura, and older releases kept available for systems as far back as OS X 10.9 Mavericks. Both Intel based Macs and Apple silicon Macs are listed as supported. The download is offered directly and the site links a sponsorship page rather than a price.

Three capabilities separate it from the built-in pane. Simple key mappings can be set from a graphical interface, so the common case of moving one key to another needs no configuration file. A set of predefined rules written by the community can be imported from the internet, and the examples named on the site are informative about the sort of problem people bring to it: diamond cursor layouts, Emacs key bindings anywhere in the system, Vi key bindings, preventing an unintended Command-Q, and mouse keys. And rules can be written from scratch, which is where per application behaviour and multi key sequences live.

The cost is that a remapping layer becomes part of the machine. It has to be granted input monitoring, it survives restarts because it is installed rather than issued as a command, and a mapping that becomes muscle memory now belongs to software rather than to macOS. That is a reasonable trade for a key pressed hundreds of times a day. It is not a reasonable trade for curiosity.

The three routes side by side

Route	Reaches	Survives a restart	What it costs
Modifier Keys pane in System Settings	Modifier keys and Caps Lock, per keyboard	Yes	Nothing. Ships with macOS
hidutil command	Any key to any other key	No. Lost on restart or when the keyboard service ends	A launch agent if the change has to persist
Karabiner-Elements	Any key, sequences, per application rules	Yes	Third party software in the input path

Nothing in the table is exclusive. A common arrangement uses the pane for the modifier swap, because a setting that ships with the system will still be there after the next macOS upgrade, and adds a third party layer only for the one or two mappings the pane cannot express. Keeping the split that way means that if the extra software is ever removed, the keyboard does not revert to something unusable.

Read the table in order, not by feature count. The pane answers the Windows keyboard question and the Caps Lock question, which together cover most searches for a key remapper. The command answers the question of whether a proposed mapping is actually better, before anything is installed. The third party layer answers the question that remains.

Remapping a key is not the same as reassigning a shortcut

A large share of the frustration that leads to a key remapper is not about keys at all. It is about a shortcut landing on the wrong command, and the tool for that is a different pane.

In System Settings, Keyboard, Keyboard Shortcuts, the App Shortcuts section creates a key combination for a menu command in any macOS app, including the Finder. The Application pop-up menu selects one app or All Applications, and the menu command is typed into a Menu title field exactly as it appears in the app, using -> for the arrow between levels and three periods for an ellipsis. Apple's example is Format->Font->Ligatures->Use Default in TextEdit.

Two limits in Apple's documentation are worth reading before that pane is opened. A key can be used only once in a key combination. And shortcuts can be created only for existing menu commands: a shortcut cannot be created for a general purpose task such as opening an app. A new combination that duplicates an existing one does not work, and one of the two has to change.

There is also a practical reason to prefer this pane over a remapper when either would work. A shortcut created here is recorded against a named menu command, so it is legible six months later, and it can be removed by selecting it and clicking the remove button. A remapped physical key leaves no such record, and the person most likely to be confused by it is the one who set it up, on the morning they sit down at a different Mac.

That second limit is the fork in the road. No amount of key remapping produces a key that opens something. For that, the Shortcuts app is the supported route, and a shortcut can also be run from Terminal with shortcuts run "Name of Shortcut", which means anything that can launch a command can launch it.

When the thing you want a key for is not an app

There is a version of this problem that no remapper touches, and it is worth naming because it is the reason many of these searches repeat every few months.

A keyboard shortcut works because the target is a thing the system can address: a key, a menu command, an application. On a Mac where most of the working day happens inside web services, half of what a person switches between is not addressable. Two client accounts on the same service are one application to macOS. A mail account, a calendar, a project board and an admin panel are four tabs in one window, and macOS has no concept of them. Command-Tab reaches the browser. It cannot reach the fourth tab from the left, and neither can a remapped Caps Lock, because there is no menu command and no application to aim at.

The structural answer is to make those things separate again, which is what a browser that keeps each web app in its own window does. When a service holds its own window and its own session, it becomes a target: it appears in the application switcher, it accepts a shortcut, and the account that belongs to one client stays signed in independently of the account that belongs to another. The way those separate spaces are organised is set out in Workspaces, and which services are handled this way is listed in Supported apps. For anyone who reaches for a remapper mainly to cut down on switching, that is the layer where the switching actually lives, and a keyboard driven setup for it is described in Built-in terminal.

What to change first

Open System Settings, Keyboard, Keyboard Shortcuts, Modifier Keys, and make the one change that stops a daily annoyance, on the keyboard it applies to. Test anything more ambitious with a hidutil command first, since it disappears at the next restart and costs nothing to abandon. If the real goal is fewer switches rather than different keys, the target needs to be a window instead of a tab, which is what a browser like SpaceDeck is for.