Remap individual keys separately for each keyboard.
Good to know
-
Get it on GitHub
Unclaimed
Are you @pqrs-org?Claim it, and your coding agent keeps it current with each release
Written by 
Are you @pqrs-org?Claim it, and your coding agent keeps it current with each release
Thanks. Marked useful.
Thanks. The report went to osfeed, and the line gets checked against the repository.
Remap keys and pointing-device buttons on your Mac, and apply custom rules for different applications and devices.
What you can do with Karabiner-Elements
Choose function-key mappings for each keyboard.
Good to know
-
Wrong?
Apply remapping rules according to the active application, device or variable.
Good to know
-
Wrong?
Import, edit and disable custom remapping rules.
Good to know
-
Wrong?
Keep different remapping setups in profiles and switch between them.
Good to know
-
Wrong?
Control pointer movement and scrolling with customized mouse or gamepad inputs.
Good to know
Gamepad support covers DirectInput devices; XInput is not supported.
Wrong?
Inspect keyboard and pointing events in EventViewer.
Good to know
EventViewer needs the applicable macOS input permissions.
Wrong?
Select profiles and set remapping variables from the command line.
Good to know
Requires the installed command-line tool.
Wrong?
Show all 49
Use trackpad finger information in complex remapping rules.
Good to know
Enable Multitouch Extension in Settings.
Wrong?
Show custom messages and sticky-modifier status on screen.
Good to know
-
Wrong?
Open applications from custom key mappings.
Good to know
-
Wrong?
Check for new Karabiner-Elements versions from the app.
Good to know
-
Wrong?
Adjust mouse movement and wheel scrolling with separate device multipliers.
Good to know
-
Wrong?
Use headset buttons as remapping inputs.
Good to know
Requires a supported headset button event.
Wrong?
Choose whether individual output events run using conditions.
Good to know
Requires custom Complex Modifications rules.
Wrong?
Switch to an application from the frontmost-application history.
Good to know
-
Wrong?
Choose whether to ignore vendor events for a device.
Good to know
The setting cannot be enabled for Apple devices in the UI.
Wrong?
Map keys to zoom, sleep, audio controls and search.
Good to know
-
Wrong?
See warnings for invalid remapping JSON and competing macOS modifier mappings.
Good to know
-
Wrong?
Remap keys on macOS 26 Tahoe.
Good to know
Requires macOS 26 on Intel or Apple Silicon.
Wrong?
Use calculated expressions and time values in remapping rules.
Good to know
Requires custom Complex Modifications rules.
Wrong?
Temporarily turn off all modifications from EventViewer.
Good to know
-
Wrong?
Set environment variables for Karabiner-Elements through a configuration file.
Good to know
-
Wrong?
Remap programmable consumer-device buttons, including supported foot pedals.
Good to know
The device must expose the supported Consumer Usage Page usage.
Wrong?
Map microphone, selection and system app-menu keys.
Good to know
-
Wrong?
Skip selected applications when switching through application history.
1 other tool for: Exclude apps from historyGood to know
-
Wrong?
List or watch Multitouch Extension variables from the command line.
Good to know
Requires Multitouch Extension for relevant input variables.
Wrong?
Read macOS log messages from Karabiner-Elements Settings.
Good to know
-
Wrong?
Change remapping behavior according to the focused UI element.
Good to know
Requires Accessibility permission.
Wrong?
Apply application conditions to overlay windows such as Spotlight.
Good to know
Requires Accessibility permission.
Wrong?
Generate Complex Modifications rules by writing JavaScript.
Good to know
-
Wrong?
Trigger actions handled by an external command receiver from key mappings.
Good to know
Requires an external server built with Karabiner-Elements-user-command-receiver.
Wrong?
Pass original pressed events through a complex remapping rule.
Good to know
-
Wrong?
Choose output when another key is pressed during a mapping.
Good to know
-
Wrong?
Remap keyboards whose events cannot be opened through the usual HID capture.
Good to know
Off by default; cannot capture Secure Event Input, distinguish source devices, or preserve physical Caps Lock transitions. It can modify devices disabled in Devices.
Wrong?
Filter the macOS log messages shown in Settings.
Good to know
-
Wrong?
Map keys to keyboard-layout selection and desktop overview controls.
Good to know
-
Wrong?
Import JavaScript files or single-rule JSON as Complex Modifications.
Good to know
-
Wrong?
Filter the Complex Modifications list to find rules.
Good to know
-
Wrong?
Swap ISO layout-specific keys for an individual device.
Good to know
-
Wrong?
Use buttons 6–8 on supported ELECOM trackballs.
Good to know
Supported models include ELECOM HUGE, HUGE PLUS and DEFT.
Wrong?
Capture raw device events and input records in EventViewer.
Good to know
-
Wrong?
Feed remapping variable updates to the command-line tool through standard input.
Good to know
Requires newline-delimited JSON objects.
Wrong?
Evaluate a JavaScript rule file and print its returned object as JSON.
Good to know
The evaluated JavaScript must return an object.
Wrong?
Adjust notification-window appearance and the duration of custom messages.
Good to know
-
Wrong?
Choose whether pointing-device events are modified by default.
Good to know
-
Wrong?
Apply application-specific remaps to unbundled GUI applications.
Good to know
-
Wrong?
Condition remaps on the title of the focused element's window.
Good to know
Requires Accessibility permission.
Wrong?
Remap keys on macOS 27 Golden Gate on Apple Silicon.
Good to know
Apple Silicon only.
Wrong?
Before you upgrade Karabiner-Elements
Newest firstOpen `Karabiner-Elements.app` after upgrading to re-enable automatic startup of its services.
Read the evidence
Wrong?
Open Multitouch Extension settings from the Karabiner-Elements menu; its separate menu has been integrated there.
Read the evidence
Wrong?
Karabiner-EventViewer and the Settings window now close after an upgrade.
Read the evidence
Wrong?
Show 17 older
`ask_for_confirmation_before_quitting` is removed; the quit menu always includes confirmation, including when the old option was false.
Read the evidence
Wrong?
The loader no longer validates `available_since` as a string; it treats the field as an unknown key.
Read the evidence
Wrong?
Update checks run periodically instead of only at startup; `check_for_updates_on_startup` is migrated to `check_for_updates` when the new key is absent.
Read the evidence
Wrong?
Sign local builds with an Apple Development or Developer ID identity. When switching signer, re-grant background-service and Accessibility permissions; reset them and restart macOS if needed.
Read the evidence
Wrong?
Enable Accessibility permission for `Karabiner-Core-Service` in System Settings.
Read the evidence
Wrong?
Only Accessibility permission is requested when it also satisfies Input Monitoring requirements.
Read the evidence
Wrong?
EventViewer adds a button to clear user variables.
Read the evidence
Wrong?
`open_application` excludes non-application bundles from `frontmost_application_history_index`.
Read the evidence
Wrong?
The default `f6` mapping changes to Do Not Disturb.
Read the evidence
Wrong?
The system extensions viewer moves from EventViewer to Settings.
Read the evidence
Wrong?
Enable `Karabiner-Elements Privileged Daemons v2` under App Background Activity and `Karabiner-Core-Service` under Input Monitoring in System Settings.
Read the evidence
Wrong?
If `karabiner.json` was moved to another location, grant Full Disk Access to `Karabiner-Core-Service` if needed. This replaces `karabiner_grabber`; standard setups do not need Full Disk Access.
Read the evidence
Wrong?
Stop reading `/Library/Application Support/org.pqrs/tmp/karabiner_grabber_devices.json`; it is no longer updated. Check devices with EventViewer or `karabiner_cli`.
Read the evidence
Wrong?
Error messages in the Complex Modification Editor can now be copied.
Read the evidence
Wrong?
Stop reading `/Library/Application Support/org.pqrs/tmp/karabiner_grabber_manipulator_environment.json`; it is no longer updated. Use EventViewer to inspect current variables.
Read the evidence
Wrong?
Apple vendor events are always processed, even if `ignore_vendor_events` is manually enabled in `karabiner.json`.
Read the evidence
Wrong?
Use Xcode 26 or later to build from source; the documented minimum increased from Xcode 16.3.
Read the evidence
Wrong?
Karabiner-Elements release history 10
Keep remapping immediately after a Mac wakes soon after going to sleep.
Details
The release fixes a 30-second remapping interruption after rapid sleep/wake and stuck modifiers with fallback capture.
Download the v16.3.0 macOS package from this release.
Now works: Remap individual keys separately for each keyboard.Now works: Remap keyboards whose events cannot be opened throu…Now works: Check for new Karabiner-Elements versions from the…Limit lifted: Use buttons 6–8 on supported ELECOM trackballs.
Seeded by @iluxav with Codex
Read the evidence
Import custom remapping rules directly from JavaScript or single-rule JSON files.
Details
Complex Modifications gains expanded import formats, filtering and notes; EventViewer can capture raw input, and the CLI can read variable updates from stdin.
Also: Older upgrades must reopen the app to restore startup; Multitouch settings move into the main menu.
Download the v16.2.0 macOS package from this release.
Added: Import JavaScript files or single-rule JSON as Comp…Added: Filter the Complex Modifications list to find rules.Added: Swap ISO layout-specific keys for an individual dev…Added: Use buttons 6–8 on supported ELECOM trackballs.Added: Capture raw device events and input records in Even…Added: Feed remapping variable updates to the command-line…Added: Evaluate a JavaScript rule file and print its retur…Added: Adjust notification-window appearance and the durat…Added: Choose whether pointing-device events are modified…Added: Apply application-specific remaps to unbundled GUI…Added: Condition remaps on the title of the focused elemen…Added: Remap keys on macOS 27 Golden Gate on Apple Silicon.Action requiredBehavior changed: Use trackpad finger information in complex remappin…Behavior changedBehavior changed / inferredNow works: Remap individual keys separately for each keyboard.Behavior changed / inferred: Import, edit and disable custom remapping rules.
Seeded by @iluxav with Codex
Read the evidence
- pqrs-org/Karabiner-Elements/releases/tag/v16.2.0
- pqrs-org/Karabiner-Elements/blob/v16.2.0/src/bin/cli/src/main.cpp
- pqrs-org/Karabiner-Elements/blob/v16.2.0/README.md
- pqrs-org/Karabiner-Elements/blob/v16.2.0/src/share/core_configuration/details/global_conf…
- pqrs-org/Karabiner-Elements/blob/v16.2.0/src/apps/ConsoleUserServer/swift/KarabinerConsol…
- pqrs-org/Karabiner-Elements/blob/v16.2.0/src/share/core_configuration/details/profile/com…
Use zoom-in and zoom-out mappings with the intended direction.
Details
The swapped zoom codes are corrected; Settings adds log filtering and update checks become periodic.
Download the v16.1.0 macOS package from this release.
Now works: Map keys to zoom, sleep, audio controls and search.Added: Filter the macOS log messages shown in Settings.Added: Map keys to keyboard-layout selection and desktop o…Behavior changed / inferred: Check for new Karabiner-Elements versions from the…Now works: Keep different remapping setups in profiles and swi…Action required
Seeded by @iluxav with Codex
Change remapping behavior when a text area or an overlay such as Spotlight has focus.
Details
Accessibility-backed conditions detect focused UI elements and overlays; Settings can generate Complex Modifications JSON from JavaScript.
Also: Requires Accessibility permission; also adds JavaScript rule authoring and optional fallback keyboard capture.
Download the v16.0.0 macOS package from this release.
Added: Change remapping behavior according to the focused…Added: Apply application conditions to overlay windows suc…Added: Generate Complex Modifications rules by writing Jav…Added: Trigger actions handled by an external command rece…Added: Pass original pressed events through a complex rema…Added: Choose output when another key is pressed during a…Added: Remap keyboards whose events cannot be opened throu…Action requiredBehavior changedNow works: Remap individual keys separately for each keyboard.Now works: Use calculated expressions and time values in remap…Now works: Import, edit and disable custom remapping rules.Now works: Keep different remapping setups in profiles and swi…Behavior changed: Inspect keyboard and pointing events in EventViewer.
Seeded by @iluxav with Codex
v15.9.0
with v15.8.0
with v15.8.0
Exclude selected applications when switching through your application history.
Details
v15.8.0 adds application-history exclusions and Multitouch variable inspection; v15.9.0 restores background update notification windows.
Also: F6 now defaults to Do Not Disturb; Settings includes macOS logs.
Download the v15.9.0 macOS package from this release.
Added: Skip selected applications when switching through a…Behavior changed: Switch to an application from the frontmost-applica…Behavior changed: Choose function-key mappings for each keyboard.Added: List or watch Multitouch Extension variables from t…Added: Read macOS log messages from Karabiner-Elements Set…Behavior changed: Inspect keyboard and pointing events in EventViewer.Now works: Show custom messages and sticky-modifier status on…Now works: Use trackpad finger information in complex remappin…Now works: Check for new Karabiner-Elements versions from the…
Seeded by @iluxav with Codex
Release held modifiers reliably after complex remapping rules finish.
Details
The core service is renamed to Karabiner-Core-Service and needs renewed macOS permissions; the connected-device JSON export stops updating.
Download the v15.7.0 macOS package from this release.
Now works: Apply remapping rules according to the active appli…Action requiredAction requiredAction requiredBehavior changed: Import, edit and disable custom remapping rules.
Seeded by @iluxav with Codex
Read the evidence
Write remapping conditions that calculate values and compare elapsed time.
Details
Complex rules add expression conditions, expression-based variable updates and a millisecond clock; EventViewer can temporarily disable modifications.
Download the v15.6.0 macOS package from this release.
Added: Use calculated expressions and time values in remap…Added: Temporarily turn off all modifications from EventVi…Added: Set environment variables for Karabiner-Elements th…Added: Remap programmable consumer-device buttons, includi…Action requiredBehavior changed: Choose whether to ignore vendor events for a device.Now works: Inspect keyboard and pointing events in EventViewer.Limit lifted / inferred: Remap keys on macOS 26 Tahoe.Added: Map microphone, selection and system app-menu keys.Action required / inferred
Seeded by @iluxav with Codex
See when invalid configuration or macOS modifier mappings interfere with your remaps.
Details
Settings adds a JSON parse-error alert, a macOS modifier-remapping warning and an option to show additional menu items.
Download the v15.5.0 macOS package from this release.
Added: See warnings for invalid remapping JSON and competi…Added: Remap keys on macOS 26 Tahoe.Now works: Choose function-key mappings for each keyboard.Behavior changed / inferred
Seeded by @iluxav with Codex
Adjust mouse movement and scrolling independently for each device.
Details
Devices settings adds movement and wheel multipliers; complex rules gain conditional outputs and application-history selection.
Also: Also adds headset input, conditional output events and controls for noisy or simultaneous input.
Download the v15.4.0 macOS package from this release.
Added: Adjust mouse movement and wheel scrolling with sepa…Added: Use headset buttons as remapping inputs.Added: Choose whether individual output events run using c…Added: Switch to an application from the frontmost-applica…Added: Choose whether to ignore vendor events for a device.Now works: Control pointer movement and scrolling with customi…Now works: Choose function-key mappings for each keyboard.Behavior changed: Apply remapping rules according to the active appli…Behavior changed: Remap individual keys separately for each keyboard.Behavior changed: Inspect keyboard and pointing events in EventViewer.Behavior changedAdded: Map keys to zoom, sleep, audio controls and search.Action required / inferredAction required / inferred
Seeded by @iluxav with Codex
Read the evidence
- pqrs-org/Karabiner-Elements/releases/tag/v15.4.0
- pqrs-org/Karabiner-Elements/blob/v15.4.0/src/apps/SettingsWindow/src/View/ExpertView.swift
- pqrs-org/Karabiner-Elements/blob/v15.4.0/README.md
- pqrs-org/Karabiner-Elements/compare/v15.3.0...v15.4.0
- pqrs-org/Karabiner-Elements/blob/v15.4.0/appendix/cg_event_set_flags/CMakeLists.txt
v15.4.0
Starting point
Starting point
Remap your Mac's keyboard for the way you use individual apps and devices.
Details
This baseline records capabilities that predate the release window: per-device key mappings, conditional rules, profiles, pointing controls and input inspection.
Existing capabilities at v15.4.0; download the macOS package. This version lists macOS 13–15 on Intel and Apple Silicon.
Added: Remap individual keys separately for each keyboard.Added: Choose function-key mappings for each keyboard.Added: Apply remapping rules according to the active appli…Added: Import, edit and disable custom remapping rules.Added: Keep different remapping setups in profiles and swi…Added: Control pointer movement and scrolling with customi…Added / inferred: Inspect keyboard and pointing events in EventViewer.Added: Select profiles and set remapping variables from th…Added: Use trackpad finger information in complex remappin…Added: Show custom messages and sticky-modifier status on…Added: Open applications from custom key mappings.Added: Check for new Karabiner-Elements versions from the…
Seeded by @iluxav with Codex