pqrs-org/karabiner-elements

Karabiner-Elements is a powerful utility for keyboard customization on macOS Sierra (10.12) or later.

Karabiner-Elements

Karabiner-Elements is a powerful utility for keyboard customization on macOS Sierra or later.

Download

You can download Karabiner-Elements from the official site.

Alternatively, for users of homebrew, Karabiner-Elements may be installed with brew install --cask karabiner-elements.

Old releases

You can download previous versions of Karabiner-Elements from here.

Supported systems

• macOS 11 Big Sur
• macOS 12 Monterey
• macOS 13 Ventura
• macOS 14 Sonoma

Usage

https://karabiner-elements.pqrs.org/docs/

Donations

If you would like to contribute financially to the development of Karabiner-Elements, donations can be made via https://karabiner-elements.pqrs.org/docs/pricing/

---

For developers

How to build

System requirements to build Karabiner-Elements:

• macOS 12+
• Xcode 13.3+
• Command Line Tools for Xcode (xcode-select --install)
• xz (brew install xz)
• XcodeGen (brew install xcodegen)
• CMake (brew install cmake)

Steps

1. Get source code by executing the following command in Terminal.app.

   git clone --depth 1 https://github.com/pqrs-org/Karabiner-Elements.git
   cd Karabiner-Elements
   git submodule update --init --recursive --depth 1

2. (Optional) If you have a codesign identity:

   1. Find your codesign identity.

      security find-identity -p codesigning -v | grep 'Developer ID Application'

      The result is as follows.

      1) 8D660191481C98F5C56630847A6C39D95C166F22 "Developer ID Application: Fumihiko Takayama (G43BCU2T37)"
      

      Your codesign identity is 8D660191481C98F5C56630847A6C39D95C166F22 in the above case.

   2. Set environment variable to use your codesign identity.

      export PQRS_ORG_CODE_SIGN_IDENTITY=8D660191481C98F5C56630847A6C39D95C166F22

   3. Find your codesign identity for installer signing.

      security find-identity -p basic -v | grep 'Developer ID Installer'

      The result is as follows.

      1) C86BB5F7830071C7B0B07D168A9A9375CC2D02C5 "Developer ID Installer: Fumihiko Takayama (G43BCU2T37)"
      

      Your codesign identity is C86BB5F7830071C7B0B07D168A9A9375CC2D02C5 in the above case.

   4. Set environment variable to use your codesign identity for installer signing.

      export PQRS_ORG_INSTALLER_CODE_SIGN_IDENTITY=C86BB5F7830071C7B0B07D168A9A9375CC2D02C5

3. Build a package by executing the following command in Terminal.app.

   make package

   The make script will create a redistributable Karabiner-Elements-VERSION.dmg in the current directory.

Note about pre-built binaries in the source tree

Karabiner-Elements uses some pre-built binaries in the source tree.

• src/vendor/Karabiner-DriverKit-VirtualHIDDevice/dist/Karabiner-DriverKit-VirtualHIDDevice-*.dmg
• Sparkle.framework in src/apps/SettingsWindow/

The above make package command does not rebuild these binaries.
(These binaries will be copied in the distributed package.)

If you want to rebuild these binaries, you have to build them manually.
Please follow the instruction of these projects.

karabiner-elements's Issues

fn constantly pressed

I mapped my Caps Lock to F16 which opens Alfred.
This is my config:

{
    "profiles": [
        {
            "name": "Default profile",
            "selected": true,
            "simple_modifications": {
                "caps_lock": "f16"
            }
        }
    ]
}

But it stopped working with the last version. Event viewer is showing this:

I'm not touching Fn, in fact I don't even have that key on my keyboard.

The problem is Alfred is not starting up now, and even if I go to change shortcut, it's registering it as F16 as it should. But it's not firing up and (when in finder for example) I hear a beep (like unrecognized key).

Improve ISO Keyboard Layout

Coming from a decades of PC usage I am completely lost without Karabiner on Sierra and Karabiner's "Improve ISO Keyboard Layout" I was using.

Current fix to swap section key § with ` and plus minus ± with tilde ~ is a lifesaver:

"non_us_backslash": "grave_accent_and_tilde"

But, is it possible to make rest of old ISO settings in new karabiner.json ( '' to additional Enter, '§' to '' and '' to '' )?

Thanks in advance

hold command|alt spacebar Siri shortcut

With Karabiner-Elements active, the hold command|alt spacebar shortcuts for Siri in macOS Sierra are not working. This is not a big deal, but maybe still worth the bug report.

Thanks for the effort of getting Karabiner to work with macOS Sierra!

Export old Karabiner prepared setting to use here

Hi,

I'm probably pushing it here, but is there any chance to export the old prepared settings (for Slovenian in my case) to have as a reference when building karabiner.json?

Thanks for the info.

Warning bell triggered when using modifier key in some applications

If Karabiner Elements is running, using Cmd/Opt/Ctrl/Shift (alone or as part of valid keyboard shortcut) will trigger the warning bell. I've only experienced it while Finder and Karabiner Elements are the frontmost application (doesn't seem to happen with Safari, iTerm2, Messages, iTunes and others).

I didn't notice this in the previous version of Karabiner Elements.

Karabiner Elements v0.90.25
macOS 10.12 beta (16A313a)
2012 15" MacBook Pro w/ Retina Display

Remote desktop modifier keys broken

When using Microsoft remote Desktop application "Version 8.0.34 (Build 27181)" there is a problem with the modifier keys.

No modifier keys are registered within the application (Shift, Control, Windows key etc), this is true for my external and builtin keyboard. Everything works fine outside the RDP application.

My simple config:

~/.karabiner.d/configuration ❯ cat karabiner.json
{
"profiles": [
{
"name": "Default profile",
"selected": true,
"simple_modifications": {
"caps_lock": "left_control",
"left_option": "left_command",
"left_command": "left_option"
}
}
]
}

Map keypress with modifier to multiple keypress

I'm looking to recreate the following macro I had set up in Karabiner under 10.11:

<autogen>
        __KeyToKey__ KeyCode::ESCAPE, MODIFIERFLAG_EITHER_LEFT_OR_RIGHT_OPTION,
        KeyCode::A, KeyCode::B, KeyCode::C, KeyCode::RETURN
</autogen>

Is this not yet possible with the new syntax?

How to modify key-repeat rate?

How do I modify the key repeat rate and the initial key repeat delay?

Thanks, keep up the good work :)

option/command 'Modifier Keys...' configuration ignored

I have a Razer Blackwidow keyboard that has a windows keyboard layout. For it I have configured from the 'Modifier Keys...' section of the keyboard settings to have the 'option' and 'command' keys switched.
When Karabiner-Elements is active this configuration is disregarded. This didn't happen for the old Karabiner.

hidd CPU usage

After installing Karabiner I noticed that hidd process CPU usage is between 4-6% while typing. That is a pretty high number if you consider battery life.

Transmission.app crashing while Karabiner Elements is running

If Karabiner Elements is running, pressing a key while using Transmission causes the app to crash. I presume this might happen with other applications, too. Error message:

Exception Name: NSRangeException
Description: -[__NSCFConstantString characterAtIndex:]: Range or index out of bounds
User Info: (null)

0   CoreFoundation                      0x00007fffbc3277bb __exceptionPreprocess + 171
1   libobjc.A.dylib                     0x00007fffd0a86a2a objc_exception_throw + 48
2   CoreFoundation                      0x00007fffbc3a4a65 +[NSException raise:format:] + 197
3   CoreFoundation                      0x00007fffbc2a0686 -[__NSCFString characterAtIndex:] + 102
4   Transmission                        0x000000010954c180 Transmission + 131456
5   AppKit                              0x00007fffba7a37ec -[NSWindow(NSEventRouting) _reallySendEvent:isDelayedEvent:] + 4086
6   AppKit                              0x00007fffba7a242a -[NSWindow(NSEventRouting) sendEvent:] + 541
7   AppKit                              0x00007fffba643a1c -[NSApplication(NSEvent) sendEvent:] + 4768
8   AppKit                              0x00007fffb9f29009 -[NSApplication run] + 1002
9   AppKit                              0x00007fffb9ef3a8a NSApplicationMain + 1237
10  Transmission                        0x000000010952e7b3 Transmission + 10163
11  Transmission                        0x000000010952e300 Transmission + 8960
12  ???                                 0x0000000000000001 0x0 + 1

Karabiner Elements v0.90.25
macOS 10.12 beta (16A313a)
2012 15" MacBook Pro w/ Retina Display

Fast input source switching is broken

Input source switching is typically bound to something like Cmd+Space. With Karabiner running, if you hit the shortcut fast, input source is not switched, but if you hold it long enough (0.5-1s) the macOS input source switching pop-up appears. That is really inconvenient for multi-language setups.

Possibly related issue: #36.

Remapping Capslock to Escape and Control (CapsLock to F19)

I'm sorry if this has been answered, but is it possible with this version of Karabiner to remap CapsLock to Escape when tapped and Control when held? Or do we still have to wait for a new version of Seil for that?

How to set key repeat speed

I've upgraded to macOS Sierra just to find out that Karabiner (which I have many mappings and speed configuration) is incompatible. I've installed Elements. How do I change the default key repeat latency? The examples are only for swapping/changing keys, or am I missing something?

Features & Config Wiki

Could you create a wiki(?) that lists the features of Karabiner vs Karabiner-Elements?

• supported yes/no
• sample from the Karabiner xml
• sample on how to convert them to the new syntax

At the moment it is hard to figure out what will work with Karabiner-Elements.

modifier flags in karabiner.json

Hi, just made the mistake of upgrading to macOS sierra! Happy you're at work on this and would love to help.

I'm wondering how to add modifier flags to karabiner.json like I had in my private.xml file for mapping escape to shift + command:

<?xml version="1.0"?>
<root>
    <item>
        <name>esc to command+shift</name>
        <identifier>private.esc_to_cmd_shift</identifier>
        <autogen>
            __KeyToKey__
            KeyCode::ESCAPE,
            KeyCode::SHIFT_L, ModifierFlag::COMMAND_L
        </autogen>
    </item>
</root>

I'm assuming it won't be under simple_modifications, but I can't find anywhere in the code for adding a more complex modification. Do you know when I might be able to use this functionality?

shift-click broken

I just installed the latest Karabiner-Elements on my iMac running the Sierra GM. I love that the "fn" key once again works as left control, but shift-click no longer works to extend the selection. Reasonable trade-off, but slightly annoying.

Here's my karabiner.json:

{
    "profiles": [
        {
            "name": "Default profile",
            "selected": true,
            "simple_modifications": {
                "fn": "left_control"
            }
        }
    ]
}

Korean Hangul-to-Hanja Input (as before in pre-Sierra Karabiner)?

Hello All, and especially Fumihiko:

Many thanks for the great work!!! Very much appreciated!

I have a question regarding where to find Sierra documentation about the new key codes. The INPUT METHOD for Korean "Hanja" (Chinese characters ... what's "Kanji" in the Japanese context) does not work for several major programs such as Microsoft Word 2011 and 2016. In other programs, e.g. Apple's Pages or even Microsoft's Excel, it does work fine. The "old" Karabiner offered a nice workaround for that.

I see Fumihiko's list here on the Github page:
https://github.com/tekezo/Karabiner-Elements/blob/master/src/share/types.hpp
And then this one at the Apple Developer site (WITHOUT explanations of what these codes do -- or am I missing something?):
https://developer.apple.com/reference/iokit/1592915-anonymous?language=objc
Furthermore, I see the SAMPLE file "japanese_pc_keyboard.json" that comes with the Karabiner-Elements beta. If I am not mistaken (?) the Hangul-to-Hanja input file should look somewhat similar.

Anyone can help locating the codes that relate to KOREAN input?

Thank you so much!
Frank

DANISH_DOLLAR missing in the keys definition

In the old Karabiner I had the option to remap § to ` with, to make the UK keyboard behave like the US one:

    <item>
        <name>Put Tilda where it belongs on Apple Keyboards</name>
        <identifier>private.tilda</identifier>
        <autogen>__KeyToKey__ KeyCode::DANISH_DOLLAR, KeyCode::BACKQUOTE</autogen>
        <device_only>DeviceVendor::APPLE_COMPUTER, DeviceProduct::ANY</device_only>
    </item>

Unfortunately I don't see the DANISH_DOLLAR key defined in the types list. Would be really glad if this were added! Thanks.

How to set right_shift = command+space?

How to set right_shift = command+space?

Can we set device limit now?

want to use different profile for different devices.

Keyboard wizard broken

Hi!
This seems to break the macOS keyboard type detection wizard (Change Keyboard Type). When it asks you to click a key it says that you're clicking on the builtin Macbook keyboard, instead of the external one.

how can use double key mapping ?

command + j = down_arrow

how to config Control+L instead of right arrow?

I just wanna change the Control+L =>Right Arrow Control+J=>Left Arrow
It had a selection in Karabiner, and how to write the karabiner.json for Karabiner-Elements?

and I did not find the karabiner.json file located the ~/.karabiner.d/configuration/
I should create it manually?

Emacs broken

I'm running version 0.90.27 of Karabiner-Elements.

I have a karabiner.json file that swaps the "fn" and "control" keys, but this problem happens without any karabiner.json file at all.

The Karabiner-Elements key swap works fine, everywhere but in Emacs.

I'm running version 25.1.1 of Emacs, downloaded from https://emacsformacosx.com/, but the same problem happens in the older version 24.5.1. 25.1.1 was released only a couple of days ago, but I've been running 24.5.1 for many months.

The problem is that I have to type control or meta keys twice before they register. I have the command key acting as meta, via this in my ~/.emacs file:

  (setq mac-command-modifier 'meta
        mac-option-modifier nil)

If I type a non-control-modified key, I have to type the next control-modified key twice. After that each control-modified key works correctly.

If I type a non-meta-modified key, I have to type the next meta-modified key twice. After that, each meta-modified key works correctly.

I really love having "fn" act as "control" in my other apps, but I live in emacs. If that doesn't work correctly, none of the rest of it matters. So I'm not currently using Karabiner-Elements.

Eject key is not available for mapping

As far as I can see I am not able to map the 'pause' key to the 'eject' key.
Previously I mapped the 'pause' key to the 'power' key for my PC keyboard to be able to lock my screen using the keyboard (control-shift-power) but this does not work (although the mapping seems to work since the 'pause' key does not produce a beep anymore).
My guess is that the new Karabiner-Elements emulates a Mac keyboard where it thinks an 'eject' key is present instead of a 'power' key so the keyboard shortcut must be e.g. control-shift-eject to lock the screen.
Unfortunately Karabiner-Elements does not allow 'eject' in the configuration.

Thanks for all the hard work!

Is it possible to try it somehow?

Is there a way to use kext's from this repo to be used with Karabiner/Seil?

P.S. I had to add

#pragma clang diagnostic ignored "-Wnonnull"

in the beginning of src/grabber/grabber/include/human_interface_device.hpp to build the project.

"Enable Sicky keys" setting on preference does not affect

On Preference.app>Accessibility>Keyboard>Enable Sticky keys.
It does not affect when I type texts.
For example,

1. Forcus on Terminal.app
2. Press Shift key
3. Displayed translucent Shift icon on screen
4. Type any alphabet on terminal
5. Inputted lower case character
6. Shift icon still on screen

It seems that Sticky icon affects on mouse operations.

Support for Microsoft Natural Keyboard 4000 Hotkeys. #703

tekezo/Karabiner#703

Fn keys work only once then die

I have Apple Keyboard with Numeric Keypad - English (USA) and after starting Karabiner Elements I can press Fn keys only ONCE, after key performs function all Fn keys enter strange state - eg F5/F6 become brightness up/down, F3/F4 do nothing....

Eg. brightness can be set only once and then Fn keys go crazy.
If I exit Karabiner Elements, Fn keys work again.

This happens with or without config.

When they "die" event viewer give me this:
F1 - 0x3
F2 - 0x2
F3 - nothing
F4 - nothing
F5 - 0x16
F6 - 0x15
F7 - 0x12
F8 - 0x10
F9 - 0x11
F10 - 0x7
F11 - 0x1
F12 - 0x0

edit: more details. fn keys are not dead, just misplaced?

Multiple key strokes as one

Anyway that we could use karabiner-elements to simulate a combo of "cmd+opt+ctrl" using "Caps Lock"?

Bluetooth Wireless Mouse doesn't work

Hello.
I used the latest Karabiner-Elements v0.90.36. My Mac's version is 10.12 Sierra. I editor the karabiner.json to switch Option Key to Command Key. It works on my keyboard very well(also Buletooth wireless keyboard).
But on the while my bluetooth wireless mouse doesn't work(Logitech MX Master).
When i quit Karabiner-Elements, my mouse can work again.

Thank you for provider this excellent software. Can you tell me how to fix it?
Thanks very much!

Input method switch shortcut is broken

I just found that Karabiner-Elements breaks input method switch.
In default, macOS uses ctrl+space to switch between current and previous input method. After opening Karabiner, it doesn't work. (But long press ctrl+space to switch between all input methods still works).

This also occurs even when I don't custom anything, so I think it's a bug?
In the event viewer, I found that when Karabiner-Elements opened, it shows 4 logs in each press of cmd, opt, ctrl keys instead of 2. Maybe it's the reason.

Force Input Source

How to use VK_CHANGE_INPUTSOURCE_ENGLISH from old Karabiner?

Overwriting key remapping of macOS settings.

Found an issue that Karabiner would overwrite macOS built-in key remap in default.
For example, I switched option and command key in the macOS settings, then when I open Karabiner-Elements, it would change back. So I have to use simple_modifications in Karabiner to switch again. However since Karabiner-Elements doesn't support remap for specific keyboard now, I have to switch between different profiles to apply correct remap file.

Control_L to Control_L (+ when you type Control_L only, send Escape)

Is there a way I can get a command like that above working with the new JSON format?

Swap Key and Shift+Key functionality?

I looked through event_manipulator.hpp and configuration_core.hpp, but I didn't find anything that made me think this is possible yet. I'm just wondering if I'm missing something?

To be clear, I'm looking for the ability to invert the actions for one specific key. i.e. the semicolon key sends a colon, and shift-semicolon sends a semicolon.

German keyboard settings for Karabiner Elements

Hello,

at the moment i'm lost with OSX Sierra, because i don't know how exactly i could reproduce my old Karabiner configuration. Is is possible emulate the following config?

$cli set remap.german_adapt_option_r_to_pcs_altgr_2 1
$cli set remap.german_optionLessthan_to_pipe 1
$cli set remap.german_optionbeta2backslash 1
$cli set remap.german_adapt_option_r_to_pcs_altgr_1 1
$cli set general.dont_remap_apple_keyboard 1
$cli set ignore_apps.remote_desktop 1
$cli set ignore_apps.virtual_machine 1
$cli set general.dont_remap_internal 1

Thank you!

xml to json config file converter

Hi,

First of all, very thanks and congrats first release.
I have experience that downgraded to El Capitan because of can not use Karabiner...
I was deal by hard editing the keyboard layout(.bundle), but it does not need them anymore.
Thanks great works.

BTW, Karabiner-Elements seems to have not configuration file backward compatibility (right?).
I'm not troubled because my custom is few and simply remap key to key only. I'm hand-rewrite it from scratch now.

But some users would have a lot of custom.
Do you have plans to implement support of old xml syntax, or xml to json converter?
If not planned, I will consider to write the simple converter for karabiner specific syntax.

I'm not have C++ experience(reading only), So can contribute only in it...

Still not read the all source, If already implemented, sorry, ignore it.
I was a lot of learn macOS interface from Karabiner sources. Thanks again for great works.

Configuration Format

Would it be possible to use Hjson as a configuration format instead of plain JSON?

Hjson avoids a lot of mistakes people make when editing JSON. It is also very lightweight and can be converted to JSON by a tool (so you don't have to change your config logic).

Section § key definisiton missing

Key definition is missing for the Section key: § (and ± with shift), code 0x0A in types.hpp so it is not possible, for example, to swap it with grave_accent_and_tilde.

How to configure right cmd as ctrl?

Profiles

Please, when possible add profiles, If I configure my gaming keyboard all the time I want to use macbook default keyboard I need to quit the application.

Greetings

F13 remap issue

Hiya,

I remapped the caps lock key to F13 and tried to use it as a iTerm2 hide/show hotkey.
In the settings dialog it looks fine as "F13", however when I press it the window doesn't show up.
Also if I'm in a terminal the capital letter "P" is printed.

Changing from "f13" in the config file to "international1" and using that as a hotkey works without any problems.

Something wrong with F13 in particular?

A few essential (for me) Karabiner/Seil features

Not sure how far is development, but the primary Karabiner features I use(d) are:

• Eject to sleep display (⏏ -> Control-Shift-⏏)
• Quarter-step volume always (F11/12 -> Option-Shift-F11/12)
• Quarter-step display brightness always (F1/2 -> Option-Shift-F1/2)
• Quarter-step keyboard backlight brightness always (F5/6 -> Option-Shift-F5/6)

Neo2 Fixes

I would like to use karabiner to configure neo2 for macOS sierra. Unfortunately i can not find the config options for the json. http://wiki.neo-layout.org/wiki/Neo%20auf%20dem%20Apple%20Macintosh%20einrichten

Any help would be highly appreciated.

In VM / RDC?

Is there any support for mapping keys only in some programs? In particular I swap the Command and Option keys, but only for remote desktops and VMs. For those wondering why, the Command key on a Mac keyboard is where an Alt key is on a Windows keyboard.

• Command_L --> Option_L (only in virtual machine, RDC)
• Option_L --> Command_L (only in virtual machine, RDC)

I'm happy to manually create the configuration file, but I don't see a way to restrict to particular programs or classes of programs.

(Honestly, I don't know why every RDC program for Mac doesn't already offer this. I had to switch to Jump Desktop when I upgraded to Sierra and register every Alt key I use - and I'm an emacs user so there are tons. But it still fails a lot.)

'fn' to 'left_control' mapping works only for builtin keyboard

This is my karabiner.json

{
    "profiles": [
        {
            "name": "Default profile",
            "selected": true,
            "simple_modifications": {
                "fn": "left_control"
            }
        }
    ]
}

It works perfect for the builtin macbook pro keyboard, but not for the offical wireless mac keyboard...
Any ideas?

howto short/long (sticky) keypress? (Ctrl/Esc et al.)

Karabiner-Elements (just installed) works well: many thanks @tekezo !

I would like to setup a feature for CapsLock :

• short CapsLock keypress = Escape
• long CapsLock keypress + other key = Control + other key

[edit: I think it was called: Control_L to Control_L (+when you type Control_L only, send Escape)
]

Do you have a template for that or some guidance?

Regards

Pressing keys causes beeping, even outside Karabiner Elements

I'm using Karabiner Elements 0.90.27. Here is my karabiner.json

{
    "profiles": [
        {
            "name": "Default profile",
            "selected": true,
            "simple_modifications": {
                "fn": "left_control",
                "f12": "delete_forward"
            }
        }
    ]
}

I can reproduce the issue like this:

• Open Karabiner Elements window and type some letters (like asdf). This will cause it to start beeping for each letter.
• Type some command keys, like Ctrl, Option, Command. These will also beep.
• Now use the mouse to switch to another application, say Chrome.
• Type the command keys, Ctrl, Option, Command. These will continue to beep, although they seem otherwise functional.
• As soon as you type a letter in the other application, the beeping goes away.

The beeping in the other application is the bug here, but personally, I would rather not have any beeping even in Karabiner Elements, as its annoying, and seems unnecessary.