karabiner-elements.pqrs.org

What is Karabiner-Elements?

Karabiner-Elements is a free, open-source keyboard customizer for macOS. It sits between your physical keyboard and macOS, intercepting key presses and letting you remap them — swap Caps Lock for Escape, turn a key into a modifier only when held, or trigger complex sequences from a single press. Remapping happens at the system level, so it applies across all your apps rather than inside one program.

Who it is for

• Writers and programmers who want Emacs-style navigation (Ctrl-f, Ctrl-b, Ctrl-n) or Vi-style bindings in every text field, not just inside one editor.
• Users of compact or non-Apple keyboards who need to correct key positions, swap Command and Option, or make a Windows-layout board behave like a Mac one.
• Anyone with a repeated-strain issue who wants to move frequently used shortcuts off awkward reaches, such as turning Caps Lock into a second Control key.
• Tinkerers who want conditional behavior — a key that does one thing tapped and another held, or shortcuts that only fire in a specific app.

What it offers

The app is built around three levels of use, and the official page describes them directly:

• Simple GUI mapping — basic key-to-key changes are configured without writing any code.
• Predefined community rules — the project points to a large library of ready-made configurations you can import from the internet, covering things like Emacs key bindings anywhere, Vi bindings, a "diamond cursor" layout for arrow keys under the home row, and a safeguard against accidentally quitting apps with Command-Q.
• Custom rules — you can modify an existing rule or write one from scratch when your needs go beyond the presets.

Trade-offs to weigh

A concrete scenario

Say you use a 60% keyboard and miss having arrow keys. Rather than relearning a new layout, you map right Command, Option and the keys around them into a diamond-shaped arrow cluster, then use a held modifier to restore their normal function. That is a rule you build once and forget about — which is exactly the kind of problem this tool is designed for.

Next step

Before installing, check the supported systems list and confirm which build matches your macOS version, since older releases need older builds. Then decide whether you are starting from a community preset or a blank rule: importing an existing rule first is the fastest way to learn the configuration syntax before writing your own. The project is free and open source, with an optional sponsorship link if you want to support development. For a broader look at macOS automation and keyboard utilities, Raycast and Hammerspoon cover adjacent ground, though neither replaces system-level key remapping the way this does.

How do I remap a key like Caps Lock to Escape or Control in Karabiner-Elements?

Karabiner-Elements can remap Caps Lock to Escape, Control, or a long list of other keys on macOS, and the basic remap is done entirely in the graphical interface — no configuration file editing required.

The simple remap via GUI

The site describes the app as a "powerful and stable keyboard customizer for macOS" with an "Easy to use" mode where you "configure simple key mappings from GUI." That is the path to use for a one-to-one Caps Lock swap.

1. Open Karabiner-Elements and select the Simple Modifications tab.
2. Pick the keyboard you want to change (the app lists connected devices separately, so a built-in keyboard and an external one can differ).
3. Click Add item, then choose caps_lock in the "From key" column.
4. Choose escape or left_control in the "To key" column.

The change applies immediately and persists across reboots. If Caps Lock now does nothing useful for you, this is the fastest way to get an Escape key within reach of the left pinky, which matters most to Vim, Emacs and terminal users.

When one key should do two jobs

A pure remap means you lose Caps Lock entirely. If you want Caps Lock to act as Control when held but still toggle capitals when tapped, that is a more advanced rule than Simple Modifications. The site points to "Complex Modifications" and a library of "predefined rules by community" that you "import from the Internet," including examples such as Emacs key bindings anywhere, Vi key bindings, and preventing unintended Command-Q. Those imported rules are the practical route for dual-role keys; writing your own JSON rule is the flexible fallback the site also documents.

Choosing between Escape and Control

Practical next step

Decide first whether you can live without Caps Lock as a capitals key. If yes, use Simple Modifications and pick Escape or Control. If no, import a community rule for the dual-role behaviour, and check the release notes before updating, since the site lists separate downloads for macOS 27 Golden Gate, macOS 26 Tahoe, macOS 15 Sequoia, macOS 14 Sonoma and macOS 13 Ventura, with older builds for Monterey, Big Sur and Catalina — matching the build to your OS version avoids compatibility surprises. Both Intel-based Macs and Apple Silicon Macs are supported.

Which version of Karabiner-Elements should I download for my macOS version and Apple Silicon or Intel Mac?

Choose the newest Karabiner-Elements release that still lists your macOS version as supported, then pick the download for your Mac type. The official download list splits by macOS version, not by Intel versus Apple Silicon: both Intel-based Macs and Apple Silicon Macs are supported, so the same macOS-appropriate installer serves either machine.

How to decide

1. Check your macOS version: Apple menu → About This Mac.
2. In the Karabiner-Elements download list, find your macOS version and take the release shown for it.
3. If your macOS is newer than the listed versions, use the newest download (the current top entry, v16.3.0) — it covers the latest macOS releases plus the recent ones below.
4. If your macOS is older, use the older branch the page lists for it (for example, the v14.x line for Monterey and Big Sur, v13.x for Catalina 10.15.6+, and so on down to the El Capitan-era builds).

Quick comparison

Practical notes

• Apple Silicon vs Intel: no separate build is called out, so trust the macOS version as the deciding factor. If you are on an Apple Silicon Mac, staying on a current macOS and the current release avoids the older branches that predate those machines.
• The reason to match versions rather than always grabbing the newest file: older macOS releases may not run the newest build, and the page explicitly keeps older downloads available for that purpose.
• First-time setup matters more than the version number for many people: Karabiner-Elements needs macOS permissions (input monitoring, accessibility) to remap keys, so expect to grant those after installing.
• What you get once installed: simple key mappings through a GUI, a large set of community predefined rules (Diamond cursor, Emacs key bindings anywhere, Vi key bindings, preventing unintended Command-Q, mouse keys), and the option to write your own rules.

Next step: open Karabiner-Elements, match your macOS version in the download list, install, then grant the requested permissions and import a predefined rule to test that remapping works.

How can I import and use community-made predefined rules for things like Emacs or Vi key bindings?

Community rules in Karabiner-Elements are imported as configuration files, then enabled per device in the app's GUI. You do not need to write JSON by hand for the common cases.

The import-and-enable workflow

1. Find a rule set you want. The project links to community "predefined rules" collections, which include examples such as Emacs key bindings anywhere, Vi key bindings, Diamond cursor, mouse keys, and a rule to prevent unintended Command-Q.
2. Import it. In the Karabiner-Elements app, open the Complex Modifications tab and use the "Add rule" / import option to load the rule file. Rules downloaded from the Internet are added this way rather than by editing a config file manually.
3. Enable the rules you actually want. Importing a collection does not mean every rule takes effect; each rule has an enable toggle, so switch on only the ones you need.
4. Check the target device. Rules apply to the selected keyboard (and to a specific device if you choose one), so if nothing happens, confirm the rule is attached to the keyboard you are typing on.
5. Test in the app that matters. Emacs and Vi bindings are most useful in apps that do not have native Emacs or Vi modes, so verify in a plain text field or terminal rather than assuming.

Choosing between Emacs-style and Vi-style rules

Practical example

A writer who works in a browser-based editor and a terminal might enable Emacs key bindings anywhere so Ctrl-A and Ctrl-E work in both, then add Vi key bindings only for the terminal. They would keep the Command-Q guard on permanently, and leave mouse keys off unless they regularly work without a pointing device. Each of these is a separate toggle, so the setup stays narrow.

Next step

Start with one rule, enable it, and test it in the exact app you care about before adding more. If a rule misbehaves, disable it rather than editing it; only move to writing your own rules when an existing rule is close but not quite right. The project's documentation covers the JSON format for that stage, and the release notes are worth checking before upgrading macOS, since supported versions are listed per macOS release.

How do I write a custom complex modification rule in Karabiner-Elements?

Custom complex modification rules in Karabiner-Elements are written as JSON files describing conditions, manipulators and key events, then loaded from the app's config directory. The GUI handles simple key remapping; JSON is for anything conditional, layered or multi-step.

The file and folder

Complex modifications live in ~/.config/karabiner/assets/complex_modifications/. Create a .json file there, then open Karabiner-Elements → Complex Modifications → Add rule and enable it. The site's own documentation and community rule collections are the best starting points: Karabiner-Elements.

The structure

A rule file has a title, an optional maintainers, and a rules array. Each rule contains description and manipulators. Each manipulator has:

• type: usually basic
• from: the triggering key, with optional modifiers
• to: the output event(s)
• conditions: optional — frontmost app, device, variable state, input source

A worked example

To make Caps Lock act as Escape when tapped but Control when held, you need to_if_alone and to_if_held_down:

{
  "title": "Personal rules",
  "rules": [
    {
      "description": "Caps Lock: Escape when tapped, Control when held",
      "manipulators": [
        {
          "type": "basic",
          "from": { "key_code": "caps_lock", "modifiers": { "optional": ["any"] } },
          "to": [{ "key_code": "left_control" }],
          "to_if_alone": [{ "key_code": "escape" }]
        }
      ]
    }
  ]
}

Scoping rules to one app

Add a condition so a rule only fires in a given application:

"conditions": [
  { "type": "frontmost_application_if", "bundle_identifiers": ["^com\\.apple\\.Terminal$"] }
]

This is the pattern behind the site's Emacs and Vi key-binding examples: remap keys in a terminal or editor without disturbing the rest of the system. Find bundle identifiers by reading the app's Info.plist or checking the Karabiner EventViewer.

Practical notes

• Validate after every edit. A single trailing comma silently prevents the rule from loading, and Karabiner shows a warning in the Complex Modifications tab rather than failing loudly.
• Use Karabiner-EventViewer to confirm what key codes your keyboard actually sends before writing rules.
• Keep personal rules in their own file rather than editing imported community rules, so updates don't overwrite your work.
• Variables (set_variable, variable_if) let you build modal layers such as a "hyper" key that changes what other keys do.

Start with one small rule — a single remap in one app — enable it, and confirm it works before adding conditions.

Is Karabiner-Elements free, and how can I sponsor the project?

Yes. Karabiner-Elements is free to download and use. The project accepts sponsorship separately from the software itself, so you do not need to pay to install or run it.

What "free" means here

The download page lists installers for a wide range of macOS versions, from current releases back to much older ones, with separate builds for Intel-based Macs and Apple Silicon Macs. There is no purchase step described in the download flow. The project's own pricing page exists mainly to explain how the work is funded and to point to a sponsorship option rather than to sell licenses.

How to sponsor

• Open the project's pricing page and look for the "Supporting this project" section, which links to sponsorship.
• Sponsorship is voluntary: it supports ongoing maintenance, compatibility updates for new macOS releases, and the community rule collection.
• You can sponsor without expecting extra features or priority support; it is support for the project, not a paid tier.

A practical way to decide

If you rely on Karabiner-Elements daily — for example, remapping Caps Lock, swapping modifier keys, or using predefined rules such as Emacs or Vi key bindings anywhere — sponsoring is a reasonable way to keep the tool maintained across macOS upgrades. If you are just trying it out, install it first, confirm your mappings work on your Mac and keyboard, and sponsor later if it becomes part of your routine.

For background on the software itself, the official project site is Karabiner-Elements, and its source and issue tracker live at GitHub.