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 provides very finely customization of key repeat rate.
You also can accelerate key repeat rate beyond the limits of OS X.

Open "Key Repeat" tab and change "Delay Until Repeat" and "Key Repeat".

Quit from menu bar.

quit

  1. Press the "launch uninstaller" button from "Misc & Uninstall" tab.
  2. Proceed uninstallation.
  3. Then restart OS X.

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

If you want to use the latest beta version, use "Check for updates including beta versions" 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

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. Edit private.xml as you like, and press Reload XML button.
    Then, activate added settings.
  8. Completed!
    Please send your new settings to me. I'll merge them into prepared settings.
    You can send it by either following ways.

Karabiner modifies following behavior automatically without any configurations:

Overwrite keyboard repeat rate:

Karabiner overwrites keyboard repeat rate.
Please adjust from Preferences.

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

Keypad:

Key combinationResult
Fn-MKeypad 0
Fn-JKeypad 1
Fn-KKeypad 2
Fn-LKeypad 3
Fn-UKeypad 4
Fn-IKeypad 5
Fn-OKeypad 6
Fn-7Keypad 7
Fn-8Keypad 8
Fn-9Keypad 9
Fn-6Keypad Clear
Fn-/Keypad +
Fn-;Keypad -
Fn-PKeypad *
Fn-0Keypad /
Fn-MinusKeypad =
Fn-.Keypad .

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.

profiles

How to use multiple profiles

  1. Add new configuration from "MenuBar" tab.
  2. Choose the configuration from menu bar.

    profiles

  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

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

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

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, brightness controls and volume controls.

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

  1. Run the following command in Terminal.app.
    $ sudo sysctl -w karabiner.debug=1
    Password: <enter your password>
    

    Note $ is prompt. Please input from sudo.

  2. Then, key events are output to log.
    You can show log by running this command in Terminal.app.
    OS X 10.8+
    $ sudo tail -f /var/log/system.log
    Password: <enter your password>
    
    OS X 10.7
    $ sudo tail -f /var/log/kernel.log
    Password: <enter your password>
    
  3. The following messages are shown when you press keys.
    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
    
  4. Press the C key while holding down the Control key to stop the message.
  5. Disable debug mode by running this command in Terminal.app.
    $ sudo sysctl -w karabiner.debug=0
    Password: <enter your password>
    

Usage of the debug mode results

You can convert a raw key code (for example, "key 0x0037") to "KeyCode::COMMAND_L" by using KeyCode.data.

Or use KeyCode::RawValue::0x0037 in private.xml.