Step 1

Open Launchpad (or open " Applications" folder from Finder).

Then, click Karabiner.

Note If you're using KeyRemap4MacBook 7.8.0 or earlier, Preferences is in System Preferences.

Step 2

An alert about accessibility features will be shown. Click "Open System Preferences".

Then, select Karabiner_AXNotifier.

Step 3

Activate your favorite settings from prepared settings.

Karabiner uses the key repeat parameters in "System Preferences > Keyboard" in default.

Therefore, please adjust key repeat rate in "System Preferences > Keyboard".

Overwrite the system key repeat rate

If you want to use more rapid key repeat rate, you can overwrite the system key repeat rate in Karabiner.
Enable "Overwrite the key repeat values of system" and then adjust parameters.

Quit from menu bar.

Press the "launch uninstaller" button from "Misc & Uninstall" tab.

You can check for updates from "Misc & Uninstall" tab.

If you want to use the latest beta version, use "Check for beta updates" button.

AXNotifier observes these events and notifies Karabiner:

• An active application has been changed.
• A focused window's title (window name) has been changed.
• A focused ui element role (AXTextArea, AXButton, etc) has been changed.

That allows you to make following settings:

• Settings are effective in specific apps. (eg. "Change the command key only in Terminal".)
• Settings are effective in specific window name. (eg. "Disable command-w in Gmail on Google Chrome".)
• Settings are effective in specific ui element role. (eg. "Change hjkl keys to arrow keys when you are not editing text.)

Using accessibility features

AXNotifier requires using accessibility features in order to observe window title (window name) and ui element role.

If you do not need to observe these items, you can deny the request.
Please turn on "Do not show this message again".

Useful settings using AXNotifier

• Change command key to control key in RDC.
  

  
• Disable Close Tab shortcut (command-w) on Gmail.
  

  
• Use "hjkl" keys as arrow keys if you are not editing text.
  

  

How to use AXNotifier in your own settings

• Specify application in private.xml.
• Specify window name (window title) in private.xml.
• Specify ui element role in private.xml.

You can examine keyboard and mouse events by using EventViewer.
Launch EventViewer from a menu.

You can add your own settings by "private.xml".

1. Click "Open private.xml" button on "Misc & Uninstall" tab.
   

   
2. Then, Finder is opened.
   

   
3. Open private.xml with your preferred text editor.
   

   
4. Update the contents of private.xml to private.xml.
   

   
5. Press "Reload XML" button on "Change Key" tab.
   

   
6. New settings have been added.
   

   
7. Apply new setting by activating added settings.
   

   
8. Edit private.xml as you like, reload XML and activate new settings.
   
   • private.xml Reference Manual

Advanced Usage: Turning off prepared settings

You can turn off prepared settings if you don't need all prepared settings.
Turn off the "Use prepared settings" checkbox.

You can also import prepared settings into your private.xml by using <include>.
Please copy lines of checkbox.xml which you want to import.

For example, this private.xml imports "Launcher Mode v2" and "Mouse Keys Mode".

<?xml version="1.0"?>
<root>
  <include once="true" path="{{ ENV_Karabiner_Resources }}/include/checkbox/launcher_mode.xml" />
  <include once="true" path="{{ ENV_Karabiner_Resources }}/include/checkbox/mouse_keys.xml" />
</root>

Karabiner 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:

Fn-Return, Fn-Delete:

There are several ways to modify input events:

• Karabiner
• Seil: https://pqrs.org/osx/karabiner/seil.html

• System Preferences > Keyboard > Modifier Keys...

  

  

Input events will be changed by each manipulators by the following order:

1. Seil
2. System Preferences > Keyboard > Modifier Keys...
3. Karabiner

Example #1

If the following modification is specified:

1. Seil setting: command key -> option key
2. System Preferences: option key -> shift key
3. Karabiner setting: shift key -> control key

The physical command key will be changed to control key.

Example #2

Generic keys are changed by Seil and Karabiner.

1. Seil setting: escape key -> tab key
2. Karabiner setting: tab key -> delete key

The physical escape key will be changed to delete key by Seil and Karabiner.
The physical tab key will also be changed to delete key by Karabiner.

Plural settings in Karabiner

Karabiner does not allow you to recursive event modification.
If one setting is applied, other settings are ignored.

1. Karabiner setting: escape key -> delete key
2. Karabiner setting: delete key -> space key

escape key will be changed to delete key. (not space key)

An application named "multi-touch extension" is attached.
You can use this application with multi-touch devices such as MacBook, Magic Mouse and Magic Trackpad.

This application activates specific setting while fingers touch the multi-touch device.
For example, you can activate Complete Vi Mode while two fingers touch the device.

ThumbSense is one of the function which multi-touch extension supplies.

How to use multi-touch extension

1. Click "Launch multi-touch extension" button in "Karabiner Preference > Misc & Uninstall".
   

   
2. Then application is launched. Click the icon in Dock.
   

   
3. Then the preference window is opened. Change checkboxes and text if needed.
   The value of "Target setting" such as notsave.thumbsense is <identifier> in XML
   

   

   

   

You can switch activated settings from menu bar.

How to use multiple profiles

1. Add new configuration from Profiles tab.
   

   

2. Choose the profile from menu bar.

   

3. Set up remapping for the selected configuration.

Switch profile by shortcut

You can find a setting which switches profile by fn+1,fn+2,fn+3, and fn+4 by searching "switch profile" on Preference.

If you want to assign your own shortcut, this is an example of private.xml.

<?xml version="1.0"?>
<root>
  <item>
    <name>Switch Profile</name>
    <identifier>private.switch_profile</identifier>
    <autogen>__KeyToKey__ KeyCode::KEY_1, ModifierFlag::FN, KeyCode::VK_OPEN_URL_APP_Karabiner_Profile0</autogen>
    <autogen>__KeyToKey__ KeyCode::KEY_2, ModifierFlag::FN, KeyCode::VK_OPEN_URL_APP_Karabiner_Profile1</autogen>
    <autogen>__KeyToKey__ KeyCode::KEY_3, ModifierFlag::FN, KeyCode::VK_OPEN_URL_APP_Karabiner_Profile2</autogen>
    <autogen>__KeyToKey__ KeyCode::KEY_4, ModifierFlag::FN, KeyCode::VK_OPEN_URL_APP_Karabiner_Profile3</autogen>
  </item>
</root>

Karabiner provides a command line interface. (karabiner command)

• You can get a list of changed setting.
• You can activate/deactivate setting.
• You can choose a profile from multiple profiles.
• You can export configuration.

How to show help

Execute the karabiner command with no argument.

$ /Applications/Karabiner.app/Contents/Library/bin/karabiner
Usage:
  Profile operations:
    $ karabiner list
    $ karabiner select INDEX (INDEX starts at 0)
    $ karabiner select_by_name NAME
    $ karabiner selected
    $ karabiner append NAME
    $ karabiner rename INDEX NEWNAME (INDEX starts at 0)
    $ karabiner delete INDEX (INDEX starts at 0)
  Settings:
    $ karabiner set IDENTIFIER VALUE
    $ karabiner enable IDENTIFIER (alias of set IDENTIFIER 1)
    $ karabiner disable IDENTIFIER (alias of set IDENTIFIER 0)
    $ karabiner toggle IDENTIFIER
    $ karabiner changed
  Others:
    $ karabiner export
    $ karabiner reloadxml
    $ karabiner relaunch
    $ karabiner be_careful_to_use__clear_all_values_by_name PROFILE_NAME

Examples:
  $ karabiner list
  $ karabiner select 1
  $ karabiner select_by_name NewItem
  $ karabiner selected
  $ karabiner append "For external keyboard"
  $ karabiner rename 1 "Empty Setting"
  $ karabiner delete 1

  $ karabiner set repeat.wait 30
  $ karabiner enable remap.shiftL2commandL
  $ karabiner disable remap.shiftL2commandL
  $ karabiner toggle remap.shiftL2commandL
  $ karabiner changed

  $ karabiner export
  $ karabiner reloadxml
  $ karabiner relaunch
  $ karabiner be_careful_to_use__clear_all_values_by_name NewItem

About "list" and "select" option

You can choose a profile from multiple profiles.

1. Get a list of profiles by "list" option.

   $ /Applications/Karabiner.app/Contents/Library/bin/karabiner list
   0: Default
   1: Don't Remap
   2: Empty
   3: Test
   

2. Choose a profile by "select" option.
   The numeral argument is a profile index. It starts from 0.

   $ /Applications/Karabiner.app/Contents/Library/bin/karabiner select 1
   

About "export" option

1. Export configuration by "export" option.
   The output is a shell script.

   $ /Applications/Karabiner.app/Contents/Library/bin/karabiner export > ~/Desktop/karabiner-import.sh
   

2. You can import it from Terminal.

   $ sh ~/Desktop/karabiner-import.sh
   ...........................................
   

Reset configuration before import

The karabiner-import.sh do not reset your configuration.
If you have enabled settings before import, the enabled settings will not be disabled in the import.

If you want to reset the configuration before import, please use be_careful_to_use__clear_all_values_by_name before running karabiner-import.sh.

$ /Applications/Karabiner.app/Contents/Library/bin/karabiner \
     be_careful_to_use__clear_all_values_by_name \
     YOUR_PROFILE_NAME
$ sh ~/Desktop/karabiner-import.sh

Karabiner's settings are stored in the following location.

Home > Library > Preferences > org.pqrs.Karabiner.plist

You can investigate a normal key code by EventViewer.
However, you cannot investigate key events which will be processed on the system side, such as Command + Tab, Mission Control key.

You have to enable debug mode in order to show these system key events.

1. Press the "Toggle Debug Mode" button in Karabiner Preferences > Misc & Uninstall tab.
   Then, enter password.

   

   

   

   

2. You can confirm the debug log by Console.app.

   Launch Console app from the "Launch Console.app" button.

   

   

   Then, the debug log will be appended when you press keys.
   You can select logs and copy them.

   

   

   Paste to text editor and confirm the log.

   Mar 21 22:19:52 rapeseed kernel[0]: org.pqrs.Karabiner --Debug-- KeyboardEventCallback [ caught]: eventType 12, flags 0x80100008, key 0x0037, kbdType  43, repeat = 0
   Mar 21 22:19:52 rapeseed kernel[0]: org.pqrs.Karabiner --Debug-- KeyboardEventCallback [sending]: eventType 12, flags 0x00040001, key 0x003b, kbdType  43, repeat = 0
   

3. Disable the debug mode by the "Toggle Debug Mode" button.
   You don't need to enter password to disable the debug mode.