Karabiner-Elements is a powerful and stable keyboard customizer for macOS.
Open Launchpad (or open Applications folder from Finder).
Then, click Karabiner-Elements.
An alert about kext policy will be shown since macOS High Sierra.
Click Open System Preferences > Security & Privacy button, then press Allow button.
Keyboard Setup Assistant will be opened.
Choose your keyboard layout.
Configure Karabiner-Elements from UI.
The following two dialog will be shown after you are logged in to ask your approval to receive keystrokes.
Press Open System Preferences button.
System Preferences will be open after you press the Open System Preferences button.
Choose Privacy tab > Input Monitoring, and then enable karabiner_grabber and karabiner_observer.
(You have to unlock configuration by the left bottom icon.)
You can change a key to another key in Simple Modifications tab.
Karabiner-Elements provides more complex event modifications.
It changes keys according to the conditions.
|Modifier flags + key to keys||
|Key to modifier flags + keys||
|Post other key events when a key pressed alone||
|Change keys in specific apps||
|Execute shell command||
You can import predefined rules from the internet (or make your own rules).
Open Complex Modifications tab and press
Add rule button, then press
Import more rules from the internet button.
Or open this page.
A web browser is opened. Press Import button in the page.
A confirmation dialog is shown. Press Allow button.
Karabiner-Elements is shown again. Press Import button, then
new rules are imported.
Press Enable button.
New rule is enabled.
Confirm the result in Karabiner-EventViewer.
Choose devices which Karabiner-Elements modifies events in
You can also disable MacBook built-in keyboard if external keyboards are connected in Devices tab.
You can change keyboard type via Keyboard Setup Assistant from System Preferences > Keyboard.
Quit from menu bar or Misc tab in Preferences.
Press the "Uninstall Karabiner-Elements" button in "Misc" tab.
If you don't want to use above GUI, you can also uninstall Karabiner-Elements from command line.
$ sudo '/Library/Application Support/org.pqrs/Karabiner-Elements/uninstall_core.sh'
You can check for updates from "Misc" tab.
If you want to use the latest beta version, use "Check for beta updates" button.
You can examine keyboard and mouse events by using EventViewer.
Launch Karabiner-EventViewer from Launchpad.
Input events will be shown when you type keyboard on EventViewer or press pointing buttons on Mouse Area.
You can switch profiles from menu bar.
Add profiles from Add profile button in Profiles tab.
You can confirm log messages in Preferences > Log tab.
Device is ignored temporarily alert will be shown if you hold keys or buttons down before Karabiner-Elements open the device.
Please press the described key or button again to dismiss the alert.
Karabiner-Elements modifies following behavior automatically without any configurations:
When you are using multiple keyboards, modifier keys are shared with
For example, pressing "shift key on keyboard1" and "space key on keyboard2" sends shift-space.
Karabiner adds fn-key combinations:
Karabiner-Elements treats input events by the following order:
Karabiner-Elements provides a command line interface which allows you to select a profile. (karabiner_cli command)
$ '/Library/Application Support/org.pqrs/Karabiner-Elements/bin/karabiner_cli' --select-profile 'Default profile'
Karabiner-Elements stores configuration to a json file which is located ~/.config/karabiner/karabiner.json
If you want to move karabiner.json to another place and make symbolic link, link to ~/.config/karabiner directory.
$ mv ~/.config/karabiner ~/Dropbox/private $ ln -s ~/Dropbox/private/karabiner ~/.config
You have to restart karabiner_console_user_server process by the following command after you made a symlink in ordre to tell Karabiner-Elements that the parent directory is changed.
$ launchctl kickstart -k gui/`id -u`/org.pqrs.karabiner.karabiner_console_user_server
Preventing event leaks is one of the most important point of Karabiner-Elements architecture design.
Karabiner-Elements treats all input events in privileged process which
is named karabiner_grabber in order to guard input events from
There is no way that malicious processes steal your input events from Karabiner-Elements.
Karabiner-Elements works with the following core components.
|Karabiner VirtualHIDDevice kernel extension||