Step 1

Open Launchpad (or open Applications folder from Finder).

Then, click Karabiner-Elements.

launchpad

Step 2

An alert about kext policy will be shown since macOS High Sierra.
Click Open System Preferences > Security & Privacy button, then press Allow button.

Step 3

Configure Karabiner-Elements from UI.

Change a key to another key

You can change a key to another key in Simple Modifications tab.

Step 1

Choose target device, then press Add item button.

Step 2

Select From key and To key.
You can investigate the key name by using Karabiner-EventViewer.

Step 3

Confirm the result in Karabiner-EventViewer.

Use more complex rules

Karabiner-Elements provides more complex event modifications.
It changes keys according to the conditions.

Examples:

Modifier flags + key to keys
  • Change control-m to return key.
  • Change control-h to delete key.
Key to modifier flags + keys
  • Change caps lock to command+control+option+shift key
Post other key events when a key pressed alone
  • Post escape key when you press left control key alone.
Change keys in specific apps
  • Change left command key to left control key in virtual machines.
Execute shell command
  • Open Activity Monitor by right shift+a

You can import predefined rules from the internet (or make your own rules).

Step 1

Open Complex Modifications tab and press Add rule button, then press Import more rules from the internet button.
Or open this page.

Step 2

A web browser is opened. Press Import button in the page.
A confirmation dialog is shown. Press Allow button.

Step 3

Karabiner-Elements is shown again. Press Import button, then new rules are imported.
Press Enable button.

Step 4

New rule is enabled.
Confirm the result in Karabiner-EventViewer.

Choose devices

Choose devices which Karabiner-Elements modifies events in Devices tab.
You can also disable MacBook built-in keyboard if external keyboards are connected in Devices tab.

Set keyboard type

You have to set keyboard type in Virtual Keyboard tab if you want to use ISO or JIS layout.

Quit from menu bar or Misc tab in Preferences.

Press the "Uninstall Karabiner-Elements" button in "Misc" tab.

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.

menu

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.

Karabiner-Elements modifies following behavior automatically without any configurations:

Share state of modifier keys with all connected keyboards:

When you are using multiple keyboards, modifier keys are shared with all keyboards.
For example, pressing "shift key on keyboard1" and "space key on keyboard2" sends shift-space.

Add fn-key combinations:

Karabiner adds fn-key combinations:

Fn-Arrow keys:

Key combinationResult
Fn-Up ArrowPageUp
Fn-Down ArrowPageDown
Fn-Left ArrowHome
Fn-Right ArrowEnd

Fn-Return, Fn-Delete:

Key combinationResult
Fn-ReturnEnter
Fn-DeleteForward Delete

Karabiner-Elements treats input events by the following order:

  1. Catch events from hardware.
  2. Apply Simple Modifications.
  3. Apply Complex Modifications.
  4. Apply Function Keys Modifications (change f1...f12 keys to media controls).
  5. Post events to applications via a virtual keyboard.
System modifier keys configuration in System Preferences > Keyboard is ignored when you use Karabiner-Elements.
Change modifier keys in Karabiner-Elements's Simple Modifications.

Karabiner-Elements provides a command line interface which allows you to select a profile. (karabiner_cli command)

Usage

$ '/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

About symbolic link

If you want to move karabiner.json to another place and make symbolic link, link to ~/.config/karabiner directory.

Example:

$ 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
Do not make a symlink to karabiner.json.
Karabiner-Elements does not reload the configuration file properly if you make a symlink to json file directly.

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 other processes.
There is no way that malicious processes steal your input events from Karabiner-Elements.

Components

Karabiner-Elements works with the following core components.

karabiner_grabber process
  • Privileged process.
  • Grab the keyboard hardware and catch events, modify events then post it to virtual devices.
karabiner_console_user_server process
  • Session user process.
  • karabiner_grabber grabs keyboards while karabiner_console_user_server is running.
  • Shell command is executed in this process.
  • Connect to karabiner_grabber via unix domain socket.
Karabiner VirtualHIDDevice kernel extension
  • Virtual keyboard and pointing device.
  • Non privileged process is forbidden to post events to virtual device.
    (Only the karabiner_grabber process can post events.