Karabiner-Elements is a powerful and stable keyboard customizer for macOS.

Core features

  • Simple Modifications: Map normal keys to arbitrary key functions.
  • Complex Modifications: Map keys by complex rules. e.g., key to modifiers, modifiers+key to key, send key event if pressed alone, etc.
  • Function Keys: Map function keys to arbitrary key functions.
  • Devices: Apply modifications to specified keyboards only.
  • Profiles: Support the creation of multiple profiles that the user can switch between.
  • Modifier Flag Sync: Synchronize modifier flags across all connected keyboards.
  • Secure Keyboard Entry Support: Work well on Secure Keyboard Entry environment such as a password prompt, terminal with Secure Keyboard Entry, etc.

Current limitations

  • Karabiner-Elements cannot modify the eject key on some keyboard (e.g., Apple Wired Keyboard) due to the limitation of macOS API.
  • Karabiner-Elements cannot modify the fn key on non Apple keyboards such as Logitech keyboards.
  • Karabiner-Elements ignores the System Preferences > Keyboard > Modifier Keys... configuration.
    Change modifiers by using Simple Modifications. (detail of input event modification chaining)

Step 1

Open Launchpad (or open Applications folder from Finder).

Then, click Karabiner-Elements.


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.

If the Allow button is not hidden after you click it, you failed to click the button.
Please follow this instruction to solve the problem.

Step 3

Two Keystroke Receiving alerts will be shown on macOS Catalina or later.
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.)

Step 4

Keyboard Setup Assistant will be opened.
Choose your keyboard layout.

Step 5

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.


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 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.

Advanced topic:

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.


This feature is useful when you put the external keybaord on top of the built-in keyboard.

You can disable the built-in keyboard from Devices > Advanced on Preferences.

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 combination Result
Fn-Up Arrow PageUp
Fn-Down Arrow PageDown
Fn-Left Arrow Home
Fn-Right Arrow End

Fn-Return, Fn-Delete:

Key combination Result
Fn-Return Enter
Fn-Delete Forward 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-MultitouchExtension is available since Karabiner-Elements 12.6.9

Karabiner-MultitouchExtension allows you to change keys only when your finger is on the trackpad.

Related Complex Modifications examples

MultitouchExtension usage

  1. Open MultitouchExtension app from Preferences > Misc.
  2. Enable "Start at login" on MultitouchExtension Preferences.
If you hid Karabiner-MultitouchExtension icon in Dock, press "Open MultitouchExtension app" button on Preferences > Misc to open Karabiner-MultitouchExtension Preferences.

How to integrate MultitouchExtension to your complex modifications

See karabiner.json reference manual.

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


Show help

$ '/Library/Application Support/org.pqrs/Karabiner-Elements/bin/karabiner_cli'

A command line utility of Karabiner-Elements.
  karabiner_cli [OPTION...]

      --select-profile arg      Select a profile by name.
      --set-variables arg       Json string: {[key: string]: number}

Switch profile

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


$ 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.


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.