Keyboard remap on a Mac: the keys that earn a new place

A request to remap a key on a Mac almost always arrives in one of three shapes. Caps Lock should behave as Control, because the muscle memory came from a different keyboard. The key beside the space bar should stop switching input sources in the middle of a sentence. Or one keystroke should jump straight to a particular window, and nothing in System Settings appears to offer that at all.

Those three sound like the same task. macOS handles them at three different layers, and choosing the wrong layer is the usual reason a remap works for an afternoon and then quietly stops. What follows is organised by layer rather than by tool. Every setting path, limit and version below was checked on macOS 27 on 26 September 2026, against Apple's documentation and against the running system.

Four layers, and one decision to make first

Before touching anything, decide which layer the change belongs to. The answer determines what the remap can reach and how long it lasts.

Layer	What it can change	Survives a restart	Scope
Keyboard settings, Modifier Keys	Caps Lock, Control, Option, Command, Function or Globe	Yes	The keyboard selected in the pane
Keyboard settings, App Shortcuts	Existing menu commands only	Yes	One app, or all apps
hidutil	Any key to any other key, below every app	No, unless something reapplies it at login	Per device, per session
Karabiner-Elements	Keys, chords, per device and per app conditions	Yes	System wide

The practical reading of that table is short. A modifier key swap belongs in the first row and needs nothing installed. A shortcut for a command that already exists in a menu belongs in the second. Anything that has to survive a reboot without a helper, or that has to behave differently in two apps, belongs in the fourth. The third row is a diagnostic tool that happens to be able to remap, which is a different thing from a place to keep a configuration.

One more distinction saves time later. Remapping moves a key to another key. Binding attaches a key to an action, such as launching an app. Apple separates these strictly, and the separation is the single most common source of disappointment for someone who expected the built in panes to do both.

The five keys that System Settings will move

The built in remapper is real, it is supported, and most people never find it because it sits three levels deep. Choose Apple menu, then System Settings, click Keyboard in the sidebar, click Keyboard Shortcuts, then select Modifier Keys in the sidebar of the sheet that opens.

The pane lists five rows: Caps Lock (⇪), Control (⌃), Option (⌥), Command (⌘), and Function (fn) or Globe (🌐), depending on the keyboard. Each row is a pop-up menu whose choices are the other modifiers plus No Action, and the instruction at the top of the pane states the model plainly: for each modifier key listed, choose the action it should perform. Apple's own worked example is the common one, setting the Caps Lock pop-up menu to Control for anyone arriving from a keyboard that had Control in that position. Restore Defaults at the bottom puts all five rows back.

The detail that matters most in this pane is the Select keyboard pop-up menu at the top. The mapping applies to the keyboard chosen there, not to the Mac. An external keyboard and the built-in one can therefore hold different mappings at the same time, which is exactly what a person wants when a PC keyboard sits on the desk on weekdays and the laptop travels at weekends. It is also why a remap appears to vanish: a different keyboard was connected, and that keyboard has its own row of settings.

Caps Lock carries one extra option in this pane, separate from the modifier list. It can be set to switch to and from the last used Latin input source. On a Mac configured for Japanese, Chinese or Korean input, that option is the answer to the complaint that Caps Lock keeps changing the typing language. Turning it off costs nothing and removes a whole class of surprise.

The limit of this layer is equally plain. Five keys, and only five. Letter keys, number keys, arrow keys and the individual keys of the function row are not here and cannot be reached from this pane.

App Shortcuts remap a menu command, not a key

The second pane is next to the first, under App Shortcuts, and it answers a different question: which keystroke should trigger a command that an app already has in its menus. Apple's documentation is unusually specific about it, and every one of those specifics is a place where an attempt fails silently.

Click the add button, then choose an application from the pop-up menu, or All Applications for a command that appears in many apps. If the app is not listed, Other opens a dialog for locating it, and Apple notes that some apps may not allow keyboard shortcuts to be set at all. Then type the menu command in the Menu title field exactly as it appears in the app, including punctuation. A submenu arrow is typed as ->, so the Ligatures command in TextEdit becomes Format->Font->Ligatures->Use Default, and an ellipsis is typed as three separate periods, so exporting becomes File->Export as PDF… typed with those three periods rather than the single ellipsis character.

Two rules close off the remaining guesswork. A key can be used only once in a combination. And shortcuts can be created only for menu commands that already exist, not for general purpose tasks such as opening an app. There is no hidden syntax for launching an application from this pane; the pane was not built for it.

Conflicts behave the way they do everywhere else in this part of macOS. If the combination is already taken by another command or another app, the new shortcut simply will not work, and one of the two has to change. Apple's troubleshooting page adds the visual cue: a warning icon appears next to a conflicting shortcut in the Keyboard Shortcuts list, and double clicking the entry allows a different combination to be pressed in its place.

hidutil sits below the keyboard, and forgets

Below both panes is the HID event system, and macOS ships a command for talking to it. Its own manual page describes hidutil as a HID event system debug utility, and the page is dated March 2016, which is a fair signal of how it is meant to be used. The property that holds a remap is UserKeyMapping, and reading it back costs nothing:

hidutil property --get "UserKeyMapping"

That prints one row per HID service on the machine with its current mapping, which makes it the fastest way to find out whether something already remapped a key on this Mac. Apple documented the write form in a developer technical note, TN2450, published as "Remapping Keys in macOS 10.12 Sierra".

Two properties of this layer decide whether it is the right choice. The first is reach: it operates beneath every application, so no app can override it, and it can move any key rather than only the five modifiers. The second is memory, and this is where the reports of trouble come from. A mapping applied this way does not persist. A restart clears it, and reconnecting the keyboard can clear it as well. Making it stick means having something reapply it at login, normally a launchd agent, and the classic symptom of a half finished setup is a command that works perfectly when typed into Terminal and appears to do nothing at all when launchd runs the same line.

Karabiner-Elements, for rules with conditions

When the rule has an "except in" clause, the built in panes run out. A key that should be Escape in one editor and Control everywhere else, a chord that fires a sequence, a mapping that applies only to one specific external keyboard: these need something that stays resident.

Karabiner-Elements is the long standing free option for that layer. The current release at the time of writing is 16.3.0, and the download page lists builds for macOS 27 Golden Gate, macOS 26 Tahoe, macOS 15 Sequoia, macOS 14 Sonoma and macOS 13 Ventura, with both Intel based Macs and Apple silicon supported. Simple key mappings are configured in its own window. Beyond that it ships predefined rules contributed by its community, including diamond cursor layouts, Emacs and Vi bindings that work in any app, mouse keys, and a rule specifically for preventing an unintended Command-Q, and it can import more of them from the internet. Rules can also be written from scratch for anything the presets do not cover.

The cost is structural rather than financial. A tool that intercepts keys before macOS sees them installs a driver extension, which means an approval step in System Settings on first run and a small amount of attention every time the operating system has a major version change. Anyone unwilling to carry that should stay in the Modifier Keys pane and accept its five rows.

Why a new remap sometimes does nothing at all

Before concluding that a mapping failed, check the list below in order. Apple documents every item on it, and between them they account for most of the reports that a remap "stopped working".

The function row is the first suspect. If a shortcut uses a function key, the Fn key or the Globe key may have to be held as well, and which keys are needed depends on the Mac model, on whether a Magic Keyboard is attached, and on how one option in Keyboard settings is set. Nothing is broken; the top row is simply doing its printed job instead of its F number job.

Next comes the app in front. Shortcuts can differ between apps, and Apple's guidance for an unexpected result is to look in the app's own menus in the menu bar, where the real binding is printed on the right hand side of each command. Layout and language belong in the same bucket: the shortcuts an app offers change with the input source, and Keyboard Viewer shows which layout is actually active.

Then the conflict icon, which is easy to miss: a warning marker next to an entry in Keyboard Shortcuts means another app already claims that combination. And last, the app version, since some shortcuts are unavailable in older builds of an app.

The switching that no keyboard layer can reach

All of the above moves keys around. None of it changes what a key can reach, and for a working day spent in Gmail, a second Gmail for another client, Slack, Notion and a support inbox, that is the limit that actually bites. Those are pages, not applications. A perfectly tuned keyboard still lands on one browser icon, and the remaining choice among a dozen tabs happens by eye.

The layer that extends a keyboard into that territory is a browser that keeps each web app in its own window with its own cookie container, so two accounts on the same service stay open side by side and each one is a target a keystroke can reach by name. The shape of that arrangement is set out on the Workspaces page, and anyone who also keeps a shell open all day will want to look at the built-in terminal rather than adding one more window to the switching list.

What to change first

Set Caps Lock to Control or Escape in the Modifier Keys pane, confirm that the Select keyboard pop-up names the keyboard actually in use, and turn off the Latin input source option on the same row if the typing language has ever changed on its own. Live with that for a week before installing anything. If the week shows that the switching which costs real time happens inside the browser rather than between apps, extend the keyboard into that layer with SpaceDeck.