diff --git a/docs/404.html b/docs/404.html
index f9dc096fe..fb9b1927e 100644
--- a/docs/404.html
+++ b/docs/404.html
@@ -82,7 +82,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/offline-search-index.7807772b4f01f8e6f5e7a25b2274e3f7.json"
+ data-offline-search-index-json-src="/offline-search-index.43a1d83ff36e29d62b5b07be4c12d599.json"
data-offline-search-base-href="/"
data-offline-search-max-results="25"
>
diff --git a/docs/docs/contact/index.html b/docs/docs/contact/index.html
index be47868c5..b098fb555 100644
--- a/docs/docs/contact/index.html
+++ b/docs/docs/contact/index.html
@@ -100,7 +100,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/offline-search-index.7807772b4f01f8e6f5e7a25b2274e3f7.json"
+ data-offline-search-index-json-src="/offline-search-index.43a1d83ff36e29d62b5b07be4c12d599.json"
data-offline-search-base-href="/"
data-offline-search-max-results="25"
>
@@ -124,7 +124,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/offline-search-index.7807772b4f01f8e6f5e7a25b2274e3f7.json"
+ data-offline-search-index-json-src="/offline-search-index.43a1d83ff36e29d62b5b07be4c12d599.json"
data-offline-search-base-href="/"
data-offline-search-max-results="25"
>
diff --git a/docs/docs/getting-started/features/index.html b/docs/docs/getting-started/features/index.html
index 2b98917f3..581e4e923 100644
--- a/docs/docs/getting-started/features/index.html
+++ b/docs/docs/getting-started/features/index.html
@@ -88,7 +88,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/offline-search-index.7807772b4f01f8e6f5e7a25b2274e3f7.json"
+ data-offline-search-index-json-src="/offline-search-index.43a1d83ff36e29d62b5b07be4c12d599.json"
data-offline-search-base-href="/"
data-offline-search-max-results="25"
>
@@ -112,7 +112,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/offline-search-index.7807772b4f01f8e6f5e7a25b2274e3f7.json"
+ data-offline-search-index-json-src="/offline-search-index.43a1d83ff36e29d62b5b07be4c12d599.json"
data-offline-search-base-href="/"
data-offline-search-max-results="25"
>
diff --git a/docs/docs/getting-started/index.html b/docs/docs/getting-started/index.html
index 186027fa1..d2957e2b6 100644
--- a/docs/docs/getting-started/index.html
+++ b/docs/docs/getting-started/index.html
@@ -83,7 +83,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/offline-search-index.7807772b4f01f8e6f5e7a25b2274e3f7.json"
+ data-offline-search-index-json-src="/offline-search-index.43a1d83ff36e29d62b5b07be4c12d599.json"
data-offline-search-base-href="/"
data-offline-search-max-results="25"
>
@@ -107,7 +107,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/offline-search-index.7807772b4f01f8e6f5e7a25b2274e3f7.json"
+ data-offline-search-index-json-src="/offline-search-index.43a1d83ff36e29d62b5b07be4c12d599.json"
data-offline-search-base-href="/"
data-offline-search-max-results="25"
>
diff --git a/docs/docs/getting-started/index.xml b/docs/docs/getting-started/index.xml
index 49806550d..381d33df2 100644
--- a/docs/docs/getting-started/index.xml
+++ b/docs/docs/getting-started/index.xml
@@ -12,7 +12,7 @@
/docs/getting-started/installation/
Mon, 01 Jan 0001 00:00:00 +0000/docs/getting-started/installation/
- Some operations are required to grant proper permission from macOS to Karabiner-Elements. Follow these instructions to set up Karabiner-Elements.
Install Karabiner-Elements Open the downloaded file. Open the .pkg file. The installer will be opened. Install Karabiner-Elements. Keep Login Items enabled Since macOS 13 Ventura, background item notifications will be shown after the installation.
The following Login Items in System Settings are required, and have to keep enabled.
Karabiner-DriverKit-VirtualHIDDeviceClient.app Karabiner-Elements.app Note If you are using macOS 12 or prior, these items are not shown in System Preferences.
+ Some operations are required to grant proper permission from macOS to Karabiner-Elements. Follow these instructions to set up Karabiner-Elements.
Install Karabiner-Elements Open the downloaded file. Open the .pkg file. The installer will be opened. Install Karabiner-Elements. After installation, you’ll need to grant the necessary permissions for Karabiner-Elements to function. This is part of macOS’s protection mechanism to prevent applications from accessing information without user consent. There are a few required steps, so please follow the instructions.Features
diff --git a/docs/docs/getting-started/installation/images/input-monitoring@2x.png b/docs/docs/getting-started/installation/images/input-monitoring@2x.png
index b64cf6091..63b7e531b 100644
Binary files a/docs/docs/getting-started/installation/images/input-monitoring@2x.png and b/docs/docs/getting-started/installation/images/input-monitoring@2x.png differ
diff --git a/docs/docs/getting-started/installation/images/installer@2x.png b/docs/docs/getting-started/installation/images/installer@2x.png
index 9682aa51a..47b0f7ed7 100644
Binary files a/docs/docs/getting-started/installation/images/installer@2x.png and b/docs/docs/getting-started/installation/images/installer@2x.png differ
diff --git a/docs/docs/getting-started/installation/images/karabiner-grabber@2x.png b/docs/docs/getting-started/installation/images/karabiner-grabber@2x.png
index 91605559d..048e70d8c 100644
Binary files a/docs/docs/getting-started/installation/images/karabiner-grabber@2x.png and b/docs/docs/getting-started/installation/images/karabiner-grabber@2x.png differ
diff --git a/docs/docs/getting-started/installation/images/keyboard-setup-assistant@2x.png b/docs/docs/getting-started/installation/images/keyboard-setup-assistant@2x.png
index 10e130b27..ceb8fcca7 100644
Binary files a/docs/docs/getting-started/installation/images/keyboard-setup-assistant@2x.png and b/docs/docs/getting-started/installation/images/keyboard-setup-assistant@2x.png differ
diff --git a/docs/docs/getting-started/installation/images/login-items0@2x.png b/docs/docs/getting-started/installation/images/login-items0@2x.png
index bf157d192..12a1bb506 100644
Binary files a/docs/docs/getting-started/installation/images/login-items0@2x.png and b/docs/docs/getting-started/installation/images/login-items0@2x.png differ
diff --git a/docs/docs/getting-started/installation/images/login-items1@2x.png b/docs/docs/getting-started/installation/images/login-items1@2x.png
index bd5ea189a..9ce71856d 100644
Binary files a/docs/docs/getting-started/installation/images/login-items1@2x.png and b/docs/docs/getting-started/installation/images/login-items1@2x.png differ
diff --git a/docs/docs/getting-started/installation/index.html b/docs/docs/getting-started/installation/index.html
index 1eac114d8..3990b8884 100644
--- a/docs/docs/getting-started/installation/index.html
+++ b/docs/docs/getting-started/installation/index.html
@@ -19,16 +19,12 @@
Installation | Karabiner-Elements
+Install Karabiner-Elements Open the downloaded file. Open the .pkg file. The installer will be opened. Install Karabiner-Elements. After installation, you’ll need to grant the necessary permissions for Karabiner-Elements to function. This is part of macOS’s protection mechanism to prevent applications from accessing information without user consent. There are a few required steps, so please follow the instructions.">
+Install Karabiner-Elements Open the downloaded file. Open the .pkg file. The installer will be opened. Install Karabiner-Elements. After installation, you’ll need to grant the necessary permissions for Karabiner-Elements to function. This is part of macOS’s protection mechanism to prevent applications from accessing information without user consent. There are a few required steps, so please follow the instructions.">
@@ -36,18 +32,14 @@
-
+Install Karabiner-Elements Open the downloaded file. Open the .pkg file. The installer will be opened. Install Karabiner-Elements. After installation, you’ll need to grant the necessary permissions for Karabiner-Elements to function. This is part of macOS’s protection mechanism to prevent applications from accessing information without user consent. There are a few required steps, so please follow the instructions.">
+
+Install Karabiner-Elements Open the downloaded file. Open the .pkg file. The installer will be opened. Install Karabiner-Elements. After installation, you’ll need to grant the necessary permissions for Karabiner-Elements to function. This is part of macOS’s protection mechanism to prevent applications from accessing information without user consent. There are a few required steps, so please follow the instructions.">
@@ -96,7 +88,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/offline-search-index.7807772b4f01f8e6f5e7a25b2274e3f7.json"
+ data-offline-search-index-json-src="/offline-search-index.43a1d83ff36e29d62b5b07be4c12d599.json"
data-offline-search-base-href="/"
data-offline-search-max-results="25"
>
@@ -120,7 +112,7 @@
aria-label="Search this site…"
autocomplete="off"
- data-offline-search-index-json-src="/offline-search-index.7807772b4f01f8e6f5e7a25b2274e3f7.json"
+ data-offline-search-index-json-src="/offline-search-index.43a1d83ff36e29d62b5b07be4c12d599.json"
data-offline-search-base-href="/"
data-offline-search-max-results="25"
>
@@ -630,8 +622,8 @@
Installed files
diff --git a/docs/offline-search-index.43a1d83ff36e29d62b5b07be4c12d599.json b/docs/offline-search-index.43a1d83ff36e29d62b5b07be4c12d599.json
new file mode 100644
index 000000000..731f2cf08
--- /dev/null
+++ b/docs/offline-search-index.43a1d83ff36e29d62b5b07be4c12d599.json
@@ -0,0 +1 @@
+[{"body":"Under normal circumstances, there is no need to read this page, as the necessary settings have already been made during the initial setup.\nHowever, we describe the macOS settings that are made during the initial setup of Karabiner-Elements for the following cases.\nIf you canceled during the initial setup and want to continue in the middle of the process If you want to check the macOS settings made during the initial setup If Karabiner-Elements is not working properly and you want to make sure that macOS is configured properly Keep background items enabled Note This setting exists only on macOS Ventura or later Karabier-Elements has processes running constantly in the background, that handle input events. You have to keep the background items enabled in macOS System Settings \u003e General \u003e Login Items.\nEnable Input Monitoring Karabiner-Elements requires Input Monitoring permission to receive and modify input events.\nYou can enable it in macOS System Settings \u003e Privacy \u0026 Security \u003e Input Monitoring.\nTroubleshooting If you cannot find karabiner_grabber or karabiner_observer in the list, this is because you have not closed the following “Keystroke Receiving” dialogs.\nkarabiner_grabber and karabiner_observer will be shown in the list after the dialogs are closed.\nAllow system extension Karabiner-Elements uses the system extension to provide a virtual keyboard and mouse. You have to approve system extension before using it. You can confirm whether the system extension already allowed in EventViewer.\nIf org.pqrs.Karabiner-DriverKit-VirtualHIDDevice appears in the System Extensions of the EventViewer and the status is [activated enabled], the system extension is already allowed.\nOtherwise, you have to approve the system extension in macOS System Settings.\nApprove system extension You can approve the system extension in macOS System Settings \u003e Privacy \u0026 Security.\n","categories":"","description":"","excerpt":"Under normal circumstances, there is no need to read this page, as the necessary settings have already been made during the initial setup.\nHowever, we describe the macOS settings that are made during …","ref":"/docs/manual/misc/required-macos-settings/","tags":"","title":"Required macOS settings"},{"body":"Usually, the following driver alert will appear on first start-up and the alert will disappear after you allow the system software from System Settings.\nUnfortunately, the allow button may sometimes not appear in System Settings due to a problem with macOS driver loading.\nIn this case, you can display the allow button by deactivating and activating driver as described in the Advanced section on the alert.\nmacOS Catalina Notes Karabiner-Elements requires macOS 10.15.6 or later, because macOS 10.15.5 or earlier has an issue around DriverKit.\nPlease use Karabiner-Elements 12.10.0 if you are using macOS 10.15.5 or earlier.\nmacOS Catalina Note #1 Even worse, there is an additional problem on the macOS side if you are using macOS Catalina. The above steps might not resolve the issue and the alert may keep showing up.\nIf you are facing the problem, restart macOS between deactivating and activating to refresh the macOS internal state.\nPress Deactivate driver button. Enter the administrator password. Restart macOS. Press Activate driver button. Open Security \u0026 Privacy System Preferences and press the allow button. macOS Catalina Note #2 The problem is caused by macOS Catalina issues around DriverKit driver.\nKarabiner-Elements v12.10.0 uses a legacy kernel extension, so it is not affected by the macOS issues. So, downgrading to Karabiner-Elements 12.10.0 also solves the issue.\n","categories":"","description":"","excerpt":"Usually, the following driver alert will appear on first start-up and the alert will disappear after you allow the system software from System Settings.\nUnfortunately, the allow button may sometimes …","ref":"/docs/help/troubleshooting/driver-alert-keeps-showing-up/","tags":"","title":"Driver alert keeps showing up"},{"body":"The allow button in Privacy \u0026 Security System Settings appear for your approval after you open Karabiner-Elements for the first time.\nHowever, this allow button may not appear in some environments.\nReason The exact cause of the issue has not been determined, but it may be caused by the corrupted system cache by a macOS issue.\nThis issue may be resolved by starting macOS in safe mode to refresh the system cache.\nSteps Restart your Mac in safe mode by this instruction. Open Karabiner-Elements from Launchpad to ensure that Allow button is shown on System Settings. Open System Settings and confirm the Allow button is shown. If the Allow button is hidden, close System Settings and open it again. Click the Allow button. Restart your Mac and boot in normal mode. Note Karabiner-Elements does not work in safe mode. You have to restart macOS in normal mode to use Karabiner-Elements. ","categories":"","description":"","excerpt":"The allow button in Privacy \u0026 Security System Settings appear for your approval after you open Karabiner-Elements for the first time.\nHowever, this allow button may not appear in some environments. …","ref":"/docs/help/troubleshooting/allow-button-does-not-appear/","tags":"","title":"Allow button in Privacy \u0026 Security System Settings does not appear"},{"body":"“Device is ignored temporarily” alert will be shown in any of the following cases:\nIf you hold keys or buttons down before Karabiner-Elements open the device. Your device sends unintented key up events regardless you do not touch the keys.\n(e.g., Swiftpoint ProPoint sends key up events of the music play key periodically.) Press the described key or button again to dismiss the alert.\n","categories":"","description":"","excerpt":"“Device is ignored temporarily” alert will be shown in any of the following cases:\nIf you hold keys or buttons down before Karabiner-Elements open the device. Your device sends unintented key up …","ref":"/docs/manual/misc/ignored-temporarily/","tags":"","title":"About \"Device is ignored temporarily\" alert"},{"body":"The allow button in Privacy \u0026 Security System Settings should be hidden after you click it. If the button does not hide after click, you did not succeed to click it.\nReason The exact cause of the issue has not been determined, but it may be caused by the corrupted system cache by a macOS issue.\nThis issue may be resolved by starting macOS in safe mode to refresh the system cache.\nSteps Restart your Mac in safe mode by this instruction. Open Karabiner-Elements from Launchpad to ensure that Allow button is shown on System Settings. Open System Settings and confirm the Allow button is shown. If the Allow button is hidden, close System Settings and open it again. Click the Allow button. Restart your Mac and boot in normal mode. Note Karabiner-Elements does not work in safe mode. You have to restart macOS in normal mode to use Karabiner-Elements. ","categories":"","description":"","excerpt":"The allow button in Privacy \u0026 Security System Settings should be hidden after you click it. If the button does not hide after click, you did not succeed to click it.\nReason The exact cause of the …","ref":"/docs/help/troubleshooting/allow-button-does-not-work/","tags":"","title":"Allow button in Privacy \u0026 Security System Settings does not work"},{"body":"Send double click event by software. cg_event_double_click ensures that the click event occurs at the same location even if the mouse cursor is moving between the first click and the second click.\n{ \"to\": [ { \"software_function\": { \"cg_event_double_click\": { \"button\": 0 } } } ] } Name Required Description button Required An integer of CGMouseButton.\n0: Left Click\n1: Right Click\n2: Middle Click\n3,4,5,…,31: Other Buttons Low responsiveness This event will be lagged since it is sent by software implementation. It is better to send pointing_button::button1 twice instead of cg_event_double_click to get a better response. Accessibility cg_event_double_click uses the accessibility features. You have to allow karabiner_console_user_server in Privacy \u0026 Security System Settings.\nExamples Sending right button double click:\n{ \"to\": [ { \"software_function\": { \"cg_event_double_click\": { \"button\": 1 } } } ] } ","categories":"","description":"","excerpt":"Send double click event by software. cg_event_double_click ensures that the click event occurs at the same location even if the mouse cursor is moving between the first click and the second click.\n{ …","ref":"/docs/json/complex-modifications-manipulator-definition/to/software_function/cg_event_double_click/","tags":"","title":"cg_event_double_click"},{"body":"You can change a key to another key on Simple Modifications tab.\nChoose target device, then press Add item button. Select keys. (Tips: The following example changes the right option key to mouse button 3) Confirm the result using Karabiner-EventViewer. Tip You can find the key name by Karabiner-EventViewer.\n","categories":"","description":"","excerpt":"You can change a key to another key on Simple Modifications tab.\nChoose target device, then press Add item button. Select keys. (Tips: The following example changes the right option key to mouse …","ref":"/docs/manual/configuration/configure-simple-modifications/","tags":"","title":"Change a key to another key"},{"body":"Karabiner-Elements configuration file paths:\n~/.config/karabiner/karabiner.json Main configuration file.\nKarabiner-Elements watches this file and reload it automatically when it is updated. ~/.config/karabiner/assets/complex_modifications Imported complex_modifications files.\nYou can use them in Karabiner-Elements Settings \u003e Complex Modifications \u003e Add predefined rule. Tip: file update detection and automatic reload Karabiner-Elements watches ~/.config/karabiner/karabiner.json and reloads it if updated.\nThe mechanism is that Karabiner-Elements watches the parent directory ~/.config/karabiner by using the File System Events API.\nThus, Karabiner-Elements fails detecting file updates after you change the parent directory (e.g., recreate the parent directory).\nLog file Error messages will be output into ~/.local/share/karabiner/log/console_user_server.log if there are errors such as parse error.\nYou can also view the error messages in Karabiner-Elements Settings \u003e Log.\n","categories":"","description":"","excerpt":"Karabiner-Elements configuration file paths:\n~/.config/karabiner/karabiner.json Main configuration file.\nKarabiner-Elements watches this file and reload it automatically when it is updated. …","ref":"/docs/json/location/","tags":"","title":"File locations"},{"body":"{ \"from\": { \"key_code\": \"The name of key_code\", \"consumer_key_code\": \"The name of consumer_key_code\", \"pointing_button\": \"The name of pointing_button\", \"any\": \"key_code or consumer_key_code or pointing_button\", \"modifiers\": { \"mandatory\": [ modifier, modifier, ... ], \"optional\": [ modifier, modifier, ... ] }, \"simultaneous\": [ { \"key_code, consumer_key_code, pointing_button or any\" }, { \"key_code, consumer_key_code, pointing_button or any\" }, ... ], \"simultaneous_options\": { \"detect_key_down_uninterruptedly\": false, \"key_down_order\": \"A restriction of input events order\", \"key_up_order\": \"A restriction of input events order\", \"key_up_when\": \"When key_up events are posted\", \"to_after_key_up\": [ to event definition, to event definition, ... ] } } } Name Required Description key_code Optional Key code which you want to change consumer_key_code Optional Consumer key code (media key code) which you want to change pointing_button Optional Pointing button name which you want to change any Optional \"any\": \"key_code\", \"any\": \"consumer_key_code\" or \"any\": \"pointing_button\" modifiers Optional Specify mandatory and optional modifiers (e.g., “change control-h to delete”) simultaneous Optional Specify multiple events which are pressed simultaneously simultaneous_options Optional Options for simultaneous Note key_code, consumer_key_code, pointing_button and any are exclusive.\nYou have to specify one of them. Caution Be careful using \"pointing_button\": \"button1\" and \"any\": \"pointing_button\".\nYou may lose the left click button and system will be unusable. Detail from.any from.modifiers from.simultaneous from.simultaneous_options Investigate key names You can find key_code, consumer_key_code and pointing_button names by EventViewer. You can also confirm names in list. (See \"data\" in the list.) Tip You can also specify key_code, consumer_key_code, pointing_button with raw number as follows.\n{ \"from\": { \"key_code\": 41 } } Do not add double quotes when you use the raw number.\nTable of Contents ","categories":"","description":"","excerpt":"{ \"from\": { \"key_code\": \"The name of key_code\", \"consumer_key_code\": \"The name of consumer_key_code\", \"pointing_button\": \"The name of pointing_button\", \"any\": \"key_code or consumer_key_code or …","ref":"/docs/json/complex-modifications-manipulator-definition/from/","tags":"","title":"from event definition"},{"body":"You can use from.any as follows.\nThese matches all key codes, consumer key codes or pointing buttons.\n\"any\": \"key_code\" \"any\": \"consumer_key_code\" \"any\": \"pointing_button\" Caution Be careful using \"any\": \"pointing_button\".\nYou may lose the left click button and system will be unusable. ","categories":"","description":"","excerpt":"You can use from.any as follows.\nThese matches all key codes, consumer key codes or pointing buttons.\n\"any\": \"key_code\" \"any\": \"consumer_key_code\" \"any\": \"pointing_button\" Caution Be careful using …","ref":"/docs/json/complex-modifications-manipulator-definition/from/any/","tags":"","title":"from.any"},{"body":"Change an event if/unless the frontmost application is the specified application.\nExample Change control-h key to delete_or_backspace except in Terminal.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"h\", \"modifiers\": { \"mandatory\": [\"control\"], \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"delete_or_backspace\" } ], \"conditions\": [ { \"type\": \"frontmost_application_unless\", \"bundle_identifiers\": [\"^com\\\\.apple\\\\.Terminal$\"] } ] } Specification { \"type\": \"frontmost_application_if\", \"bundle_identifiers\": [ bundle identifier regex, bundle identifier regex, ... ], \"file_paths\": [ file path regex, file path regex, ... ] } Name Required Description type Required \"frontmost_application_if\" or \"frontmost_application_unless\" bundle_identifiers Optional Bundle identifier regexs such as [\"^com\\\\.apple\\\\.Terminal$\", \"^com\\\\.googlecode\\\\.iterm2$\"] file_paths Optional File path regexs such as [\"/Finder$\"] description Optional A human-readable comment Multiple bundle identifiers or file paths Multiple entries in bundle_identifiers and file_paths are joined by “or”.\nThe following condition is matched if bundle identifier is “com.apple.Terminal” or “com.googlecode.iterm2”.\n{ \"type\": \"frontmost_application_if\", \"bundle_identifiers\": [ \"^com\\\\.apple\\\\.Terminal$\", \"^com\\\\.googlecode\\\\.iterm2$\" ] } Investigate the bundle identifier and file path You can find the bundle identifier and file path by EventViewer \u003e Frontmost Application tab.\nOpen EventViewer, and then switch the frontmost application to an application which you want to know the bundle identifer or file path.\n","categories":"","description":"","excerpt":"Change an event if/unless the frontmost application is the specified application.\nExample Change control-h key to delete_or_backspace except in Terminal.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"h\", …","ref":"/docs/json/complex-modifications-manipulator-definition/conditions/frontmost-application/","tags":"","title":"frontmost_application_if, frontmost_application_unless"},{"body":"Karabiner-Elements does not modify mouse devices by default.\nYou have to enable your mouse on Karabiner-Elements Settings \u003e Devices. Then, use Simple Modifications to assign a key to a button or use Complex Modifications for more advanced usage. ","categories":"","description":"","excerpt":"Karabiner-Elements does not modify mouse devices by default.\nYou have to enable your mouse on Karabiner-Elements Settings \u003e Devices. Then, use Simple Modifications to assign a key to a button or use …","ref":"/docs/help/how-to/mouse-button/","tags":"","title":"How to change mouse buttons"},{"body":"Some operations are required to grant proper permission from macOS to Karabiner-Elements. Follow these instructions to set up Karabiner-Elements.\nInstall Karabiner-Elements Open the downloaded file. Open the .pkg file. The installer will be opened. Install Karabiner-Elements. After installation, you’ll need to grant the necessary permissions for Karabiner-Elements to function. This is part of macOS’s protection mechanism to prevent applications from accessing information without user consent. There are a few required steps, so please follow the instructions.\nAdditionally, when you open Karabiner-Elements Settings, the necessary actions will be displayed, so you can follow those prompts as well.\nOpen Karabiner-Elements Settings Open Karabiner-Elements from Launchpad. Keep Login Items enabled The background item notifications will be shown after the installation.\nThe following Login Items in System Settings must be enabled.\nKarabiner-Elements Non-Privileged Agents Karabiner-Elements Privileged Daemons Note If you are using macOS 12 or prior, these items are not shown in System Preferences. Please proceed to the next step. Allow system software which provides virtual devices for Karabiner-Elements The following alert will be shown when you open Karabiner-Elements Settings. Click Open System Settings button, then press the Allow button. Note Please follow this instruction if there is any problem with the Allow button. Grant Input Monitoring to Karabiner-Elements processes The Keystroke Receiving alerts will be shown. Press the Open System Settings button on both alerts. System Settings will be opened after you press the Open System Settings button. Choose Privacy \u0026 Security \u003e Input Monitoring, and then enable karabiner_grabber.\nNote If you are using Karabiner-Elements 14.13.0 or earlier, an alert for karabiner_observer will also be displayed, so please grant permission for that as well. Setup your keyboard layout Keyboard Setup Assistant will be opened. Choose your keyboard layout. (ANSI, ISO or JIS) Configure Karabiner-Elements Enjoy keyboard configuration!\nConfiguration manual ","categories":"","description":"","excerpt":"Some operations are required to grant proper permission from macOS to Karabiner-Elements. Follow these instructions to set up Karabiner-Elements.\nInstall Karabiner-Elements Open the downloaded file. …","ref":"/docs/getting-started/installation/","tags":"","title":"Installation"},{"body":"Karabiner-Elements installs files into the following locations.\nSystem files /Applications/Karabiner-Elements.app /Applications/Karabiner-EventViewer.app /Library/Application Support/org.pqrs/Karabiner-Elements /Library/Application Support/org.pqrs/Karabiner-VirtualHIDDevice /Library/Application Support/org.pqrs/config /Library/Application Support/org.pqrs/tmp /Library/LaunchDaemons/org.pqrs.karabiner.karabiner_grabber.plist /Library/LaunchDaemons/org.pqrs.karabiner.karabiner_kextd.plist /Library/LaunchDaemons/org.pqrs.karabiner.karabiner_observer.plist /Library/LaunchAgents/org.pqrs.karabiner.agent.karabiner_grabber.plist /Library/LaunchAgents/org.pqrs.karabiner.agent.karabiner_observer.plist /Library/LaunchAgents/org.pqrs.karabiner.karabiner_console_user_server.plist /Library/LaunchAgents/org.pqrs.karabiner.karabiner_session_monitor.plist /var/log/karabiner User files ~/.config/karabiner ~/.local/share/karabiner ~/Library/Preferences/org.pqrs.Karabiner-Elements.Preferences.plist ~/Library/Preferences/org.pqrs.Karabiner-Elements.Settings.plist ~/Library/Preferences/org.pqrs.Karabiner-Elements.Updater.plist ~/Library/Preferences/org.pqrs.Karabiner-EventViewer.plist ~/Library/Preferences/org.pqrs.Karabiner-Menu.plist ~/Library/Preferences/org.pqrs.Karabiner-MultitouchExtension.plist Warning If you want to remove Karabiner-Elements, you have to use uninstaller. ","categories":"","description":"","excerpt":"Karabiner-Elements installs files into the following locations.\nSystem files /Applications/Karabiner-Elements.app /Applications/Karabiner-EventViewer.app /Library/Application …","ref":"/docs/help/advanced-topics/installed-files/","tags":"","title":"Installed files"},{"body":"mouse_motion_to_scroll changes mouse cursor movement to scroll wheel.\n{ \"type\": \"mouse_motion_to_scroll\", \"from\": { \"modifiers\": { \"mandatory\": [...], \"optional\": [...] } }, \"conditions\": ..., \"options\": { \"momentum_scroll_enabled\": true, \"speed_multiplier\": 1.0 } } Key Value Required Description type \"mouse_motion_to_scroll\" Required — from.modifiers Same as basic.from.modifiers Optional Enable mouse_motion_to_scroll if specified modifiers are pressed conditions Same as basic.conditions Optional Enable mouse_motion_to_scroll when specified conditions options An object of parameters Optional — Caution You should set either from.modifiers or conditions.\nYour mouse cursor movement will be always changed to scroll and your mouse will be unusable without from.modifiers and conditions.\nOptions Key Value Required Description momentum_scroll_enabled true or false Optional Enable Momentum scroll. The default value is true. speed_multiplier float value Optional Multiply scroll speed. The default value is 1.0. Example The following json changes button4 + mouse movement to scroll.\n[ { \"type\": \"basic\", \"from\": { \"pointing_button\": \"button4\", \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"set_variable\": { \"name\": \"enable_mouse_motion_to_scroll\", \"value\": 1 } } ], \"to_after_key_up\": [ { \"set_variable\": { \"name\": \"enable_mouse_motion_to_scroll\", \"value\": 0 } } ] }, { \"type\": \"mouse_motion_to_scroll\", \"from\": { \"modifiers\": { \"optional\": [\"any\"] } }, \"conditions\": [ { \"type\": \"variable_if\", \"name\": \"enable_mouse_motion_to_scroll\", \"value\": 1 } ] } ] ","categories":"","description":"","excerpt":"mouse_motion_to_scroll changes mouse cursor movement to scroll wheel.\n{ \"type\": \"mouse_motion_to_scroll\", \"from\": { \"modifiers\": { \"mandatory\": [...], \"optional\": [...] } }, \"conditions\": ..., …","ref":"/docs/json/complex-modifications-manipulator-definition/other-types/mouse-motion-to-scroll/","tags":"","title":"mouse_motion_to_scroll"},{"body":"Karabiner-MultitouchExtension allows you to change keys only when the finger is on the trackpad.\nYou can use variable_if or variable_unless to determine either the finger is on trackpad.\nExample The following json changes k key to up_arrow when the finger is on the trackpad.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"k\", \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"up_arrow\" } ], \"conditions\": [ { \"type\": \"variable_unless\", \"name\": \"multitouch_extension_finger_count_total\", \"value\": 0 } ] } Variables Karabiner-MultitouchExtension changes the following variables when the finger count on the trackpad is changed.\nName Value multitouch_extension_finger_count_total Total count of fingers on the trackpad multitouch_extension_finger_count_upper_half_area Count of fingers on the upper half of trackpad multitouch_extension_finger_count_lower_half_area Count of fingers on the lower half of trackpad multitouch_extension_finger_count_left_half_area Count of fingers on the left half of trackpad multitouch_extension_finger_count_right_half_area Count of fingers on the right half of trackpad Note finger_count_total == finger_count_upper_half_area + finger_count_lower_half_area finger_count_total == finger_count_left_half_area + finger_count_right_half_area You can confirm the variables state on Karabiner-EventViewer \u003e Variables.\n","categories":"","description":"","excerpt":"Karabiner-MultitouchExtension allows you to change keys only when the finger is on the trackpad.\nYou can use variable_if or variable_unless to determine either the finger is on trackpad.\nExample The …","ref":"/docs/json/extra/multitouch-extension/","tags":"","title":"MultitouchExtension integration"},{"body":"Karabiner-Elements keeps running in the background even if you close the settings window.\nTo quit Karabiner-Elements, choose “Quit Karabiner-Elements” from menu bar.\nNote If you’ve hidden the menu bar icon, you can also quit Karabiner-Elements from Settings.\n","categories":"","description":"","excerpt":"Karabiner-Elements keeps running in the background even if you close the settings window.\nTo quit Karabiner-Elements, choose “Quit Karabiner-Elements” from menu bar.\nNote If you’ve hidden the menu bar …","ref":"/docs/manual/operation/quit/","tags":"","title":"Quit"},{"body":"shell_command executes the shell command.\nExamples Open application { \"to\": [ { \"shell_command\": \"open -a 'Safari.app'\" } ] } Execute shell from file { \"to\": [ { \"shell_command\": \"/bin/sh ~/opt/shell_commands/hello.sh\" } ] } Advanced topic The very limited environment variables are passed to the command, $HOME, $UID, $USER, etc.\nExport environment variables in shell_command if your commands depend them.\nFor example, the following command does not work well with unicode characters because tr command depends the current locale.\n{ \"to\": [ { \"shell_command\": \"pbpaste | tr '[:upper:]' '[:lower:]' | pbcopy\" } ] } You have to set LC_ALL in shell_command in this case.\n{ \"to\": [ { \"shell_command\": \"export LC_ALL=en_US.UTF-8; pbpaste | tr '[:upper:]' '[:lower:]' | pbcopy\" } ] } ","categories":"","description":"","excerpt":"shell_command executes the shell command.\nExamples Open application { \"to\": [ { \"shell_command\": \"open -a 'Safari.app'\" } ] } Execute shell from file { \"to\": [ { \"shell_command\": \"/bin/sh …","ref":"/docs/json/complex-modifications-manipulator-definition/to/shell-command/","tags":"","title":"to.shell_command"},{"body":"In Allow in the Background of Login Items, Fumihiko Takayama may appear instead of Karabiner-Elements.\nThere are several causes, but the problem is mainly on the macOS side and is difficult to resolve. (Restarting macOS may solve this issue)\nIn any case, there is no problem with leaving it as it is.\nExpected:\nInformation for those who want to know more The confirmed causes are as follows:\nIf you have ever git clone the Karabiner-Elements repository and built it If macOS has set the Allow in the Background display name before Karabiner-Elements was registered in the macOS application database How to solve when you have built Karabiner-Elements from source code The Login Items referes Launch Services database to determine the display name.\nIf you have built Karabiner-Elements from source code, your built binaries in the working directory are registered Launch Services automatically.\nWe assume Login Items mixes the information of binaries in your working directory and installed from the package, and failed to get the correct information. Therefore, in Login Items, the signing developer’s name is displayed instead.\nSo purging unintended entries in Launch Services database solves this issue.\nSteps Run the following command in Terminal to get the list of registered applications.\n/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -gc -dump | grep ^path | grep Karabiner-Elements The result example:\npath: /Users/tekezo/.Trash/Karabiner-Elements.app (0x6a38) path: /Users/tekezo/Library/Developer/Xcode/DerivedData/Karabiner-Elements-aljilynxkbdxwddtylopomxdislp/Build/Products/Debug/Karabiner-Elements.app (0x6bf8) path: /Library/Application Support/org.pqrs/Karabiner-Elements/Karabiner-Menu.app (0x7918) path: /Library/Application Support/org.pqrs/Karabiner-Elements/Karabiner-NotificationWindow.app (0x7930) path: /Library/Application Support/org.pqrs/Karabiner-Elements/Karabiner-Elements.app/Contents/Frameworks/Sparkle.framework/Versions/B/Updater.app (0x7938) path: /Library/Application Support/org.pqrs/Karabiner-Elements/Karabiner-Elements.app (0x793c) path: /Applications/Karabiner-Elements.app (0x7940) path: /Library/Application Support/org.pqrs/Karabiner-Elements/Karabiner-MultitouchExtension.app (0x7944) path: /Users/tekezo/Library/Developer/Xcode/DerivedData/Karabiner-Elements-enyghegdpximkigqjnasmtnnkupb/Build/Products/Release/Karabiner-Elements.app (0x54c4) Next, unregister the path to the built binaries, those containing Xcode, build, etc, from the list.\n/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -u '/Users/tekezo/.Trash/Karabiner-Elements.app' /System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -u '/Users/tekezo/Library/Developer/Xcode/DerivedData/Karabiner-Elements-aljilynxkbdxwddtylopomxdislp/Build/Products/Debug/Karabiner-Elements.app' ... Finally, restart macOS.\n","categories":"","description":"","excerpt":"In Allow in the Background of Login Items, Fumihiko Takayama may appear instead of Karabiner-Elements.\nThere are several causes, but the problem is mainly on the macOS side and is difficult to …","ref":"/docs/help/troubleshooting/fumihiko-takayama-in-login-items/","tags":"","title":"\"Fumihiko Takayama\" is shown in Login Items"},{"body":"You can restart Karabiner-Elements from Settings.\n","categories":"","description":"","excerpt":"You can restart Karabiner-Elements from Settings.\n","ref":"/docs/manual/operation/restart/","tags":"","title":"Restart"},{"body":"You can enable the sticky modifier keys from Karabiner-Elements Settings \u003e Simple modifications.\nNote The sticky modifier keys acts as general modifier key while you are pressing and holding down the key.\nFor example, the following operation result is AA instead of Aa.\nPress sticky left shift key Press a key Release a key Press a key Release a key Release sticky left shift key If you want to disable this feature, use sticky modifier key (pressing and holding down is disabled).\nSticky modifier key indicator Sticky modifier key indicator will be shown while the sticky modifiers are active.\nYou can hide the indicator from Karabiner-Elements Settings \u003e UI.\nSticky modifiers and mouse events The sticky modifiers are not deactivate by mouse buttons if you are not enabled the mouse.\nThere are two solutions:\nDeactivate sticky modifier by press the sticky modifier key again. Enable your mouse on Devices. ","categories":"","description":"","excerpt":"You can enable the sticky modifier keys from Karabiner-Elements Settings \u003e Simple modifications.\nNote The sticky modifier keys acts as general modifier key while you are pressing and holding down the …","ref":"/docs/help/how-to/sticky-modifier-key/","tags":"","title":"How to use sticky modifier keys"},{"body":"Change an event if/unless the event is from specified device.\nExample Change 1 key to f1 if the device is Apple keyboard.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"1\", \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"f1\" } ], \"conditions\": [ { \"type\": \"device_if\", \"identifiers\": [ { \"vendor_id\": 1452 }, { \"vendor_id\": 76 } ] } ] } Specification { \"type\": \"device_if\", \"identifiers\": [ { \"vendor_id\": 1111, \"product_id\": 2222, \"description\": \"my keyboard 1\" }, { \"vendor_id\": 3333, \"product_id\": 4444, \"description\": \"my keyboard 2\" }, ... ] } Name Required Description type Required \"device_if\" or \"device_unless\" or \"device_exists_if\" or \"device_exists_unless\" identifiers Required Target device definitions description Optional A human-readable comment type Type Description Available since device_if Valid only for devices specified in identifiers Karabiner-Elements 11.0.0 device_unless Valid only for devices other than specified in identifiers Karabiner-Elements 11.0.0 device_exists_if Valid if a specified device is connected Karabiner-Elements 14.8.4 device_exists_unless Valid unless a specified device is connected Karabiner-Elements 14.8.4 identifiers identifiers is an array of objects.\nName Required Description Fixed Value vendor_id Optional Vendor ID of device Yes product_id Optional Product ID of device Yes device_address Optional Bluetooth address (Bluetooth MAC address) of device (only available for Bluetooth devices) (available since Karabiner-Elements 14.12.2) Yes [1] location_id Optional Location ID of device No [2] is_keyboard Optional true or false Yes is_pointing_device Optional true or false Yes is_game_pad Optional true or false\n(available since Karabiner-Elements 14.12.4) Yes is_touch_bar Optional true or false Yes is_built_in_keyboard Optional true or false\n(available since Karabiner-Elements 14.8.2) Yes [1] The device_address will change when you replace the hardware. [2] The location_id will change when you change the USB port which the device is connected. Multiple identifiers If you specify multiple identifiers (vendor_id, product_id, location_id, …), these are joined by “and”.\nThe following condition is matched if Vendor ID is 1111 and Product ID is 2222.\n{ \"type\": \"device_if\", \"identifiers\": [ { \"vendor_id\": 1111, \"product_id\": 2222 } ] } Multiple entries If you specify multiple entries at identifiers, conditions are joined by “or”.\nThe following condition is matched if Vendor ID is 1111 or 1112.\n{ \"type\": \"device_if\", \"identifiers\": [ { \"vendor_id\": 1111 }, { \"vendor_id\": 1112 } ] } Investigate the device identifiers You can find them by EventViewer \u003e Devices tab.\n","categories":"","description":"","excerpt":"Change an event if/unless the event is from specified device.\nExample Change 1 key to f1 if the device is Apple keyboard.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"1\", \"modifiers\": { \"optional\": …","ref":"/docs/json/complex-modifications-manipulator-definition/conditions/device/","tags":"","title":"device_if, device_unless, device_exists_if, device_exists_unless"},{"body":"Karabiner-Elements is a powerful and stable keyboard customizer for macOS.\nCore features Simple Modifications: Change normal keys to other keys. Complex Modifications: Change keys by complex rules. Change a key to combination of modifiers. (e.g. change capslock to control+command) Change modifiers+key to key. (e.g. change control+m to return) Send key events if a key is pressed alone. Send key events if keys are pressed simultaneously. Mouse keys. etc. Function Keys: Change f1-f12 keys to media controls. Devices: Apply modifications to specified keyboards only. Profiles: Support multiple profiles. 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. Extra Key Support: Enable extra keys on PC keyboard that are not recognized by default in macOS. Home key on iPad keyboards such as Logitech K480 International keys Language keys (e.g., 無変換,変換, カタカナ keys on JIS PC keyboard) Application Launch Keys 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 Settings \u003e Keyboard \u003e Keyboard Shortcuts... \u003e Modifier Keys configuration. Change modifiers by using Simple Modifications. (Detail of input event modification chaining) ","categories":"","description":"","excerpt":"Karabiner-Elements is a powerful and stable keyboard customizer for macOS.\nCore features Simple Modifications: Change normal keys to other keys. Complex Modifications: Change keys by complex rules. …","ref":"/docs/getting-started/features/","tags":"","title":"Features"},{"body":"from.modifiers is a object which has the following keys.\nKey Value Required Description mandatory An array of strings Optional Modifiers which must be pressed optional An array of strings Optional Modifiers which can be pressed from.modifiers.mandatory Events are manipulated only if mandatory modifiers are pressed. Mandatory modifiers are removed from to events. from.modifiers.optional Events are also manipulated even if optional modifiers are pressed. Optional modifiers are kept in to events. Tip If you do not include any in modifiers.optional, your manipulator does not change event if extra modifiers (modifiers which are not included in modifiers.mandatory) are pressed. List of modifiers modifiers.mandatory and modifiers.optional are array of the folowing strings.\nName Description caps_lock — left_command — left_control — left_option — left_shift — right_command — right_control — right_option — right_shift — fn — command Either left command or right command is pressed control Either left control or right control is pressed option Either left option or right option is pressed shift Either left shift or right shift is pressed left_alt Alias of left_option (available since Karabiner-Elements 12.3.0) left_gui Alias of left_command (available since Karabiner-Elements 12.3.0) right_alt Alias of right_option (available since Karabiner-Elements 12.3.0) right_gui Alias of right_command (available since Karabiner-Elements 12.3.0) any Any modifiers Examples Without modifiers This json defines manipulator which changes escape to tab.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"escape\" }, \"to\": [ { \"key_code\": \"tab\" } ] } Without modifiers, the event is changed only any modifiers are not pressed. Input Output Manipulated escape tab Manipulated left_shift + escape left_shift + escape Not manipulated left_control + escape left_control + escape Not manipulated With modifiers.optional This json defines manipulator which changes escape to tab. (left_shift and left_control can be pressed.)\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"escape\", \"modifiers\": { \"optional\": [\"left_shift\", \"left_control\"] } }, \"to\": [ { \"key_code\": \"tab\" } ] } The optional modifiers (left_shift and left_control) are kept in output events. The event is not changed if modifiers are not included in optional such as left_option. Input Output Manipulated escape tab Manipulated left_shift + escape left_shift + tab Manipulated left_control + escape left_control + tab Manipulated left_option + escape left_option + escape Not manipulated left_shift + left_option + escape left_shift + left_option + escape Not manipulated With modifiers.mandatory This json defines manipulator which changes control + h to delete_or_backspace.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"h\", \"modifiers\": { \"mandatory\": [\"control\"] } }, \"to\": [ { \"key_code\": \"delete_or_backspace\" } ] } The mandatory modifier (control) are removed in output events. The event is not changed if left_control and right_control are not pressed. Input Output Manipulated h h Not manipulated left_control + h delete_or_backspace Manipulated left_control + left_option + h left_control + left_option + h Not manipulated With modifiers.mandatory and modifiers.optional { \"type\": \"basic\", \"from\": { \"key_code\": \"h\", \"modifiers\": { \"mandatory\": [\"control\"], \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"delete_or_backspace\" } ] } The mandatory modifier (control) are removed in output events. The event is not changed if left_control and right_control are not pressed. \"optional\": [\"any\"] allows any modifiers. Input Output Manipulated h h Not manipulated left_control + h delete_or_backspace Manipulated left_control + left_option + h left_option + delete_or_backspace Manipulated left_control + left_shift + h left_shift + delete_or_backspace Manipulated ","categories":"","description":"","excerpt":"from.modifiers is a object which has the following keys.\nKey Value Required Description mandatory An array of strings Optional Modifiers which must be pressed optional An array of strings Optional …","ref":"/docs/json/complex-modifications-manipulator-definition/from/modifiers/","tags":"","title":"from.modifiers"},{"body":"Karabiner-Elements disables the caps lock delay without any action since v13.3.0.\n","categories":"","description":"","excerpt":"Karabiner-Elements disables the caps lock delay without any action since v13.3.0.\n","ref":"/docs/help/how-to/disable-caps-lock-delay/","tags":"","title":"How to disable caps lock delay"},{"body":"Karabiner-Elements modifies following behavior automatically without any configurations:\nShare state of modifier keys with all connected keyboards When you are using multiple keyboards, modifier keys are shared with all keyboards.\nFor example, pressing “shift key on keyboard1” and “space key on keyboard2” sends shift-space.\nAdd fn-key combinations Karabiner adds fn-key combinations:\nfn-arrow keys Key combination Result fn-up arrow page up fn-down arrow page down fn-left arrow home fn-right arrow end others Key combination Result fn-return enter fn-delete forward delete ","categories":"","description":"","excerpt":"Karabiner-Elements modifies following behavior automatically without any configurations:\nShare state of modifier keys with all connected keyboards When you are using multiple keyboards, modifier keys …","ref":"/docs/manual/misc/implicit-behavior/","tags":"","title":"Implicit behavior"},{"body":"It’s an issue of macOS that macOS update sometimes does not restore the running process state sufficiently after macOS update.\nPlease follow the instruction to solve the problem.\nRestart macOS once again after macOS update. Reinstall Karabiner-Elements if restart macOS does not solve the problem. ","categories":"","description":"","excerpt":"It’s an issue of macOS that macOS update sometimes does not restore the running process state sufficiently after macOS update.\nPlease follow the instruction to solve the problem.\nRestart macOS once …","ref":"/docs/help/troubleshooting/stopped-working-after-macos-update/","tags":"","title":"Karabiner-Elements stopped working after macOS update"},{"body":"Security is one of the most important point of Karabiner-Elements architecture design.\nSeparating process and running them with properly privileges to prevent event leaks.\nProcess Karabiner-Elements restricts the input event handling to karabiner_observer and karabiner_grabber processes.\nThese process are running with root privilege and other process including malicious attacker cannot steal your input events.\nList of process Running with root privilege\nkarabiner_observer Role: Observe the keyboard hardware events and tell grabber the devices state. karabiner_grabber Role: Grab the keyboard hardware and catch events, modify events then post them. Karabiner VirtualHIDDevice kernel extension Role: Virtual keyboard and pointing device. The virtual devices deny any requires (sending input events) from non root privileged processes.\nTypically, karabiner_grabber is the only process which can send input events to the virtual devices. Running with logged in user privilege\nkarabiner_console_user_server Role: Tell karabiner_grabber starting device grabbing. Execute shell commands which is triggered by karabiner_grabber. karabiner_session_monitor Role: Monitor user login status and tell it to karabiner_grabber. karabiner_observer (Running with logged in user) Role: Tell macOS karabiner_observer will be use Input Monitoring.\nAnd do nothing if the process is running with non root user. karabiner_grabber (Running with logged in user) Role: Tell macOS karabiner_grabber will be use Input Monitoring.\nAnd do nothing if the process is running with non root user. ","categories":"","description":"","excerpt":"Security is one of the most important point of Karabiner-Elements architecture design.\nSeparating process and running them with properly privileges to prevent event leaks.\nProcess Karabiner-Elements …","ref":"/docs/help/advanced-topics/security/","tags":"","title":"Security"},{"body":"Move the mouse cursor to the specified point.\n{ \"to\": [ { \"software_function\": { \"set_mouse_cursor_position\": { \"x\": 0, \"y\": 0, \"screen\": 0 } } } ] } Name Required Description x Required The new mouse cursor position y Required The new mouse cursor position screen Optional The screen index of the new mouse cursor origin Position format There are two styles to specify the position.\nType Format Example Point integer { \"x\": 100 } Percent “xx%” { \"x\": \"50%\" } Examples Set the mouse cursor position to (0,0) of the second screen.\n{ \"to\": [ { \"software_function\": { \"set_mouse_cursor_position\": { \"x\": 0, \"y\": 0, \"screen\": 1 } } } ] } Set the mouse cursor position to center of the first screen.\n{ \"to\": [ { \"software_function\": { \"set_mouse_cursor_position\": { \"x\": \"50%\", \"y\": \"50%\", \"screen\": 0 } } } ] } ","categories":"","description":"","excerpt":"Move the mouse cursor to the specified point.\n{ \"to\": [ { \"software_function\": { \"set_mouse_cursor_position\": { \"x\": 0, \"y\": 0, \"screen\": 0 } } } ] } Name Required Description x Required The new mouse …","ref":"/docs/json/complex-modifications-manipulator-definition/to/software_function/set_mouse_cursor_position/","tags":"","title":"set_mouse_cursor_position"},{"body":"{ \"key_code\": \"The name of key_code\", \"consumer_key_code\": \"The name of consumer_key_code\", \"pointing_button\": \"The name of pointing_button\", \"shell_command\": \"shell command\", \"select_input_source\": { \"language\": \"language regex\", \"input_source_id\": \"input source id regex\", \"input_mode_id\": \"input mode id regex\" }, \"set_variable\": { \"name\": \"variable name\", \"value\": \"variable value\" }, \"mouse_key\": mouse_key definition, \"sticky_modifier\": sticky modifier definition, \"software_function\": software function definition, \"modifiers\": [ modifier, modifier, ... ], \"lazy\": false, \"repeat\": true, \"halt\": false, \"hold_down_milliseconds\": 0 } Note The following keys are exclusive. You cannot specify multiple items into one to entry.\nkey_code consumer_key_code pointing_button shell_command select_input_source set_variable mouse_key sticky_modifier software_function (software_function is available since Karabiner-Elements v13.5.1) Name Required Description key_code Optional Key code which you want to post consumer_key_code Optional Consumer key code (media key code) which you want to post pointing_button Optional Pointing button name which you want to post shell_command Optional Shell command which you want to execute select_input_source Optional Input source which you want to switch set_variable Optional A varaible name and value which you want to change mouse_key Optional A mouse key definition sticky_modifier Optional A sticky modifier key definition software_function Optional A software function definition modifiers Optional Modifiers which are post with the event lazy Optional Lazy modifier flag repeat Optional Key repeat flag halt Optional A flag for to_after_key_up hold_down_milliseconds Optional Interval of key_down and key_up when these events are sent at the same time Investigate key names You can find key_code, consumer_key_code and pointing_button names by EventViewer. You can also confirm names in list. (See \"data\" in the list.) Tip You can also specify key_code, consumer_key_code, pointing_button with raw number as follows.\n{ \"to\": [ { \"key_code\": 41 } ] } Table of Contents ","categories":"","description":"","excerpt":"{ \"key_code\": \"The name of key_code\", \"consumer_key_code\": \"The name of consumer_key_code\", \"pointing_button\": \"The name of pointing_button\", \"shell_command\": \"shell command\", \"select_input_source\": { …","ref":"/docs/json/complex-modifications-manipulator-definition/to/","tags":"","title":"to event definition"},{"body":"select_input_source change the current input source.\nCaution Switching to input sources which have input_mode_id (Chinese, Japanese, Korean, Vietnamese) may be failed due to an macOS issue.\nFor CJKV input sources, sending the input source switch shortcut (e.g., control-space) is better than using select_input_source.\n{ \"to\": [ { \"select_input_source\": { \"language\": \"language regex\", \"input_source_id\": \"input source id regex\", \"input_mode_id\": \"input mode id regex\" } } ] } Name Required Description language Optional The language regex such as \"^en$\", \"^fr$\" input_source_id Optional The input source id regex such as \"^com\\\\.apple\\\\.keylayout\\\\.US$\" input_mode_id Optional The input mode id regex such as \"^com\\\\.apple\\\\.inputmethod\\\\.Japanese\\\\.Hiragana$\" Example Switch to French input source.\n{ \"to\": [ { \"select_input_source\": { \"language\": \"^fr$\" } } ] } Investigate the input source identifiers You can find the current input source identifiers by EventViewer \u003e Variables tab.\n{ \"input_source\": { \"input_mode_id\": \"com.apple.inputmethod.Japanese\", \"input_source_id\": \"com.google.inputmethod.Japanese.base\", \"language\": \"ja\" } } ","categories":"","description":"","excerpt":"select_input_source change the current input source.\nCaution Switching to input sources which have input_mode_id (Chinese, Japanese, Korean, Vietnamese) may be failed due to an macOS issue.\nFor CJKV …","ref":"/docs/json/complex-modifications-manipulator-definition/to/select-input-source/","tags":"","title":"to.select_input_source"},{"body":"Swap ; and : (Equal to swap ; and shift-;)\n[ { \"type\": \"basic\", \"from\": { \"key_code\": \"semicolon\", \"modifiers\": { \"mandatory\": [\"shift\"], \"optional\": [\"caps_lock\"] } }, \"to\": [ { \"key_code\": \"semicolon\" } ] }, { \"type\": \"basic\", \"from\": { \"key_code\": \"semicolon\", \"modifiers\": { \"optional\": [\"caps_lock\"] } }, \"to\": [ { \"key_code\": \"semicolon\", \"modifiers\": [\"left_shift\"] } ] } ] Change control-h to delete And change control-option-h to option-delete.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"h\", \"modifiers\": { \"mandatory\": [\"control\"], \"optional\": [\"caps_lock\", \"option\"] } }, \"to\": [ { \"key_code\": \"delete_or_backspace\" } ] } Disable command-l on Finder { \"type\": \"basic\", \"from\": { \"key_code\": \"l\", \"modifiers\": { \"mandatory\": [\"command\"], \"optional\": [\"caps_lock\"] } }, \"conditions\": [ { \"type\": \"frontmost_application_if\", \"bundle_identifiers\": [\"^com\\\\.apple\\\\.finder$\"] } ] } Post escape if left_control is pressed alone { \"type\": \"basic\", \"from\": { \"key_code\": \"left_control\", \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"left_control\", \"lazy\": true } ], \"to_if_alone\": [ { \"key_code\": \"escape\" } ] } Open Alfred 4 if escape is held down { \"type\": \"basic\", \"from\": { \"key_code\": \"escape\", \"modifiers\": { \"optional\": [\"caps_lock\"] } }, \"parameters\": { \"basic.to_if_alone_timeout_milliseconds\": 250, \"basic.to_if_held_down_threshold_milliseconds\": 250 }, \"to_if_alone\": [ { \"key_code\": \"escape\" } ], \"to_if_held_down\": [ { \"shell_command\": \"open -a 'Alfred 4.app'\" } ] } Change right_shift x2 to mission_control [ { \"type\": \"basic\", \"from\": { \"key_code\": \"right_shift\", \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"mission_control\" } ], \"conditions\": [ { \"type\": \"variable_if\", \"name\": \"right_shift pressed\", \"value\": 1 } ] }, { \"type\": \"basic\", \"from\": { \"key_code\": \"right_shift\", \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"set_variable\": { \"name\": \"right_shift pressed\", \"value\": 1 } }, { \"key_code\": \"right_shift\" } ], \"to_delayed_action\": { \"to_if_invoked\": [ { \"set_variable\": { \"name\": \"right_shift pressed\", \"value\": 0 } } ], \"to_if_canceled\": [ { \"set_variable\": { \"name\": \"right_shift pressed\", \"value\": 0 } } ] } } ] Change equal+delete to forward_delete if these keys are pressed simultaneously { \"type\": \"basic\", \"from\": { \"simultaneous\": [ { \"key_code\": \"equal_sign\" }, { \"key_code\": \"delete_or_backspace\" } ], \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"delete_forward\" } ] } ","categories":"","description":"","excerpt":"Swap ; and : (Equal to swap ; and shift-;)\n[ { \"type\": \"basic\", \"from\": { \"key_code\": \"semicolon\", \"modifiers\": { \"mandatory\": [\"shift\"], \"optional\": [\"caps_lock\"] } }, \"to\": [ { \"key_code\": …","ref":"/docs/json/typical-complex-modifications-examples/","tags":"","title":"Typical complex_modifications examples"},{"body":"Karabiner-Elements provides built-in uninstaller.\nUse the uninstaller to remove Karabiner-Elements from your system.\nYou can launch the uninstaller from “Launch uninstaller” button on Uninstall tab. Then, follow the instruction of the dialog. (The uninstaller ask your administrator password in order to remove files.)\nUninstall from command line If you don’t want to use above GUI, you can also uninstall Karabiner-Elements from command line.\nbash '/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/scripts/uninstall/deactivate_driver.sh' sudo '/Library/Application Support/org.pqrs/Karabiner-Elements/uninstall.sh' (Administrator password is required to run the above command.)\nAdditional uninstallation Some settings and files will remain after uninstallation. It does not affect the system even if it remains in place, but if you are concerned about them, please delete them manually.\nInput Monitoring settings Remove karabiner_grabber and karabiner_observer from the Input Monitoring settings in macOS Settings. Log files Delete the following directories: /var/log/karabiner ~/.local/share/karabiner Temporary directories Delete the following directories: /Library/Application Support/org.pqrs/tmp Setting files Delete the following directories: ~/.config/karabiner Advanced topic Operation not permitted error will occur if you try removing files by rm command.\nsudo rm -rf /Applications/Karabiner-Elements.app rm: /Applications/Karabiner-Elements.app/Contents: Operation not permitted rm: /Applications/Karabiner-Elements.app: Operation not permitted Karabiner-Elements forces you to use uninstaller to remove files in order to ensure remove files outside /Applications.\nSee Installed files to confirm the files.\nManual uninstallation If you want to remove files without uninstaller, unlock app files from command line with this instruction.\nAnd then, remove installed files by hand, and reboot your Mac.\n","categories":"","description":"","excerpt":"Karabiner-Elements provides built-in uninstaller.\nUse the uninstaller to remove Karabiner-Elements from your system.\nYou can launch the uninstaller from “Launch uninstaller” button on Uninstall tab. …","ref":"/docs/manual/operation/uninstall/","tags":"","title":"Uninstall"},{"body":"Karabiner-Elements provides more complex event modifications.\nThese rules change keys by conditions.\nExamples 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. There are two ways to add rules\nImport predefined rules maintained by the community Create your own rules In both cases, you can modify the rules later to make them more personalised.\nImport predefined rules Step 1 Open Complex Modifications tab and press Add predefined rule button, then press Import more rules from the internet button.\nOfficial rules site will be open using your default web browser.\nStep 2 Press Import button in the page.\nA confirmation dialog is shown. Press Allow button.\nStep 3 Karabiner-Elements is shown again. Press Import button, then new rules are imported.\nStep 4 Press Enable button.\nStep 5 New rule is enabled.\nConfirm the result using Karabiner-EventViewer.\nCreate your own rules Step 1 Open Complex Modifications tab and press Add your own rule button.\nStep 2 An editor will open with sample rules. Change the content and press the Save button to register.\nWhen making changes, Karabiner-EventViewer and Karabiner Configuration Reference Manual can be used to confirm the key names and how to write rules.\nEdit rules Open Complex Modifications tab and press Edit button. The editor will open. Change the contents and save it.\nWhen making changes, Karabiner-EventViewer and Karabiner Configuration Reference Manual can be used to confirm the key names and how to write rules.\n","categories":"","description":"","excerpt":"Karabiner-Elements provides more complex event modifications.\nThese rules change keys by conditions.\nExamples Modifier flags + key to keys: Change control-m to return key. Change control-h to delete …","ref":"/docs/manual/configuration/configure-complex-modifications/","tags":"","title":"Use more complex rules"},{"body":"Karabiner-Elements does not provide virtual modifiers, however you can make your own flag similar to virtual modifier using variables.\nExample The following json change keypad_1 to virtual modifier.\nChange keypad_1 to virtual modifier (my_modifier_1). Change keypad_1 + a to mission_control. Change keypad_1 + s to launchpad. [ { \"type\": \"basic\", \"from\": { \"key_code\": \"keypad_1\", \"modifiers\": { \"mandatory\": [], \"optional\": [\"any\"] } }, \"to\": [ { \"set_variable\": { \"name\": \"my_modifier_1\", \"value\": 1 } } ], \"to_after_key_up\": [ { \"set_variable\": { \"name\": \"my_modifier_1\", \"value\": 0 } } ] }, { \"type\": \"basic\", \"from\": { \"key_code\": \"a\", \"modifiers\": { \"mandatory\": [], \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"mission_control\" } ], \"conditions\": [ { \"type\": \"variable_if\", \"name\": \"my_modifier_1\", \"value\": 1 } ] }, { \"type\": \"basic\", \"from\": { \"key_code\": \"s\", \"modifiers\": { \"mandatory\": [], \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"launchpad\" } ], \"conditions\": [ { \"type\": \"variable_if\", \"name\": \"my_modifier_1\", \"value\": 1 } ] } ] ","categories":"","description":"","excerpt":"Karabiner-Elements does not provide virtual modifiers, however you can make your own flag similar to virtual modifier using variables.\nExample The following json change keypad_1 to virtual modifier. …","ref":"/docs/json/extra/virtual-modifier/","tags":"","title":"Virtual modifier"},{"body":"You can check for updates from Update tab.\nTip If you want to use the latest beta version, use “Check for beta updates” button.\n","categories":"","description":"","excerpt":"You can check for updates from Update tab.\nTip If you want to use the latest beta version, use “Check for beta updates” button.\n","ref":"/docs/manual/operation/check-for-updates/","tags":"","title":"Check for updates"},{"body":"Choose devices which Karabiner-Elements modifies events on Devices tab.\nTip Mice are disabled by default.\nYou have to enable them if you want to change the mouse buttons in Karabiner-Elements. ","categories":"","description":"","excerpt":"Choose devices which Karabiner-Elements modifies events on Devices tab.\nTip Mice are disabled by default.\nYou have to enable them if you want to change the mouse buttons in Karabiner-Elements. ","ref":"/docs/manual/configuration/configure-devices/","tags":"","title":"Choose devices"},{"body":"The manipulators are evaluated from the top to the bottom and the input event is manipulated only the first matched manipulator.\nIn other words, if there are multiple manipulators which change the same key, the manipulator placed at the top is applied and other manipulators are ignored.\nSimple Modifications and Complex Modifications Simple Modifications and Complex Modifications are independent.\nThus, Simple Modifications does not affect above priority.\nKarabiner-Elements changes keys by Simple Modifications, and then changes them by Complex Modifications.\nAbout input event modification chaining.\nExample If there are the following manipulators, right shift key will be right command + right option.\nSimple Modifications Change right shift to right command Complex Modifications Change right command to right command + right option ","categories":"","description":"","excerpt":"The manipulators are evaluated from the top to the bottom and the input event is manipulated only the first matched manipulator.\nIn other words, if there are multiple manipulators which change the …","ref":"/docs/json/complex-modifications-manipulator-evaluation-priority/","tags":"","title":"complex_modifications manipulator evaluation priority"},{"body":"simultaneous manipulates keys which are pressed simultaneously in 50 milliseconds.\nExample This json defines manipulator which changes a+s+d to mission_control.\n{ \"type\": \"basic\", \"from\": { \"simultaneous\": [ { \"key_code\": \"a\" }, { \"key_code\": \"s\" }, { \"key_code\": \"d\" } ], \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"mission_control\" } ] } Note There are some cases simultaneous does not modify events.\nsimultaneous does not modify events if any from events are released before all from events are pressed. simultaneous does not modify events if from events are interrupted by another key_down event. Manipulated input #1 Input: a key_down s key_down d key_down Output: mission_control Manipulated input #2 Input: s key_down a key_down d key_down Output: mission_control Not manipulated input #1 a is released before all input events are pressed.\nInput: a key_down s key_down a key_up d key_down Output: a key_down s key_down a key_up d key_down Not manipulated input #2 Another key (f) is pressed before all input events are pressed.\nInput: a key_down s key_down f key_down d key_down Output: a key_down s key_down f key_down d key_down About key_up The key_up event is posted when you release any from events.\nFor example, changing tab+q to mission_control works as follows.\nInput Output tab key_down — q key_down mission_control key_down tab key_up mission_control key_up q key_up — Change threshold milliseconds You can adjust threshold on Karabiner-Elements Settings \u003e Parameters.\nIt is same as adjusting basic.simultaneous_threshold_milliseconds parameter in json.\n","categories":"","description":"","excerpt":"simultaneous manipulates keys which are pressed simultaneously in 50 milliseconds.\nExample This json defines manipulator which changes a+s+d to mission_control.\n{ \"type\": \"basic\", \"from\": { …","ref":"/docs/json/complex-modifications-manipulator-definition/from/simultaneous/","tags":"","title":"from.simultaneous"},{"body":"Karabiner-Elements treats input events by the following order:\nCatch events from hardware. Apply Simple Modifications. Apply Complex Modifications. Apply Function Keys Modifications. (change f1…f12 keys to media controls) Post events to applications via a virtual keyboard. Note System modifier keys configuration in System Settings \u003e Keyboard \u003e Keyboard Shortcuts… \u003e Modifier Keys is ignored when you use Karabiner-Elements.\nChange modifier keys in Karabiner-Elements’s Simple Modifications.\n","categories":"","description":"","excerpt":"Karabiner-Elements treats input events by the following order:\nCatch events from hardware. Apply Simple Modifications. Apply Complex Modifications. Apply Function Keys Modifications. (change f1…f12 …","ref":"/docs/manual/misc/event-modification-chaining/","tags":"","title":"Input event modification chaining"},{"body":"Causes an immediate system sleep.\nAvailable since iokit_power_management_sleep_system is available since Karabiner-Elements 13.7.1. { \"to\": [ { \"software_function\": { \"iokit_power_management_sleep_system\": { \"delay_milliseconds\": 500 } } } ] } Name Required Description delay_milliseconds Optional Waiting time before the system goes to sleep Examples Use default delay_milliseconds (500 ms).\n{ \"to\": [ { \"software_function\": { \"iokit_power_management_sleep_system\": {} } } ] } ","categories":"","description":"","excerpt":"Causes an immediate system sleep.\nAvailable since iokit_power_management_sleep_system is available since Karabiner-Elements 13.7.1. { \"to\": [ { \"software_function\": { …","ref":"/docs/json/complex-modifications-manipulator-definition/to/software_function/iokit_power_management_sleep_system/","tags":"","title":"iokit_power_management_sleep_system"},{"body":"Karabiner-Elements does not provide a feature to adjust key repeat rate.\nUse System Settings \u003e Keyboard.\nYou can also adjust the key repeat rate using defaults write command. https://apple.stackexchange.com/questions/10467/how-to-increase-keyboard-key-repeat-rate-on-os-x\n","categories":"","description":"","excerpt":"Karabiner-Elements does not provide a feature to adjust key repeat rate.\nUse System Settings \u003e Keyboard.\nYou can also adjust the key repeat rate using defaults write command. …","ref":"/docs/help/how-to/key-repeat/","tags":"","title":"Is it possible to adjust the key repeat rate?"},{"body":"Change an event if/unless the event is from specified type keyboard.\nExample Change control-[ key to escape, including JIS layout support. (the [ key is close_bracket in JIS layout)\n[ { \"type\": \"basic\", \"from\": { \"key_code\": \"open_bracket\", \"modifiers\": { \"mandatory\": [\"control\"], \"optional\": [\"caps_lock\"] } }, \"to\": [ { \"key_code\": \"escape\" } ], \"conditions\": [ { \"keyboard_types\": [\"ansi\", \"iso\"], \"type\": \"keyboard_type_if\" } ] }, { \"type\": \"basic\", \"from\": { \"key_code\": \"close_bracket\", \"modifiers\": { \"mandatory\": [\"control\"], \"optional\": [\"caps_lock\"] } }, \"to\": [ { \"key_code\": \"escape\" } ], \"conditions\": [ { \"keyboard_types\": [\"jis\"], \"type\": \"keyboard_type_if\" } ] } ] Specification { \"type\": \"keyboard_type_if\", \"keyboard_types\": [\"ansi\", \"iso\"] } Name Required Description type Required \"keyboard_type_if\" or \"keyboard_type_unless\" keyboard_types Required An array of \"ansi\", \"iso\" or \"jis\" description Optional A human-readable comment Multiple keyboard types keyboard_types are joined by “or”.\nThe following condition is matched if the keyboard type is “ansi” or “iso”.\n{ \"type\": \"keyboard_type_if\", \"keyboard_types\": [\"ansi\", \"iso\"] } ","categories":"","description":"","excerpt":"Change an event if/unless the event is from specified type keyboard.\nExample Change control-[ key to escape, including JIS layout support. (the [ key is close_bracket in JIS layout)\n[ { \"type\": …","ref":"/docs/json/complex-modifications-manipulator-definition/conditions/keyboard-type/","tags":"","title":"keyboard_type_if, keyboard_type_unless"},{"body":"to_if_alone posts events when the from key is pressed alone.\nThe events are posted at the from key is released.\nExample The following json changes left_control to sending escape when left_control is pressed alone.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"left_control\", \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"left_control\", \"lazy\": true } ], \"to_if_alone\": [ { \"key_code\": \"escape\" } ] } About cancellation to_if_alone is canceled if other events (keys, buttons or scroll wheel) is happen while the from key is pressed down.\nThe cancellation also happens when you press the from key long. (The default timeout is 1000 milliseconds.)\nYou can adjust the timeout milliseconds by parameters \u003e basic.to_if_alone_timeout_milliseconds.\nThe following example sets the timeout 500 milliseconds.\n{ \"from\": ..., \"to\": ..., \"to_if_alone\": [ { \"key_code\": \"escape\" } ], \"parameters\": { \"basic.to_if_alone_timeout_milliseconds\": 500 }, \"type\": \"basic\" } About keyboard repeat to_if_alone posts both key_down and key_up events at the same time.\nThus, you cannot use key repeat for to_if_alone events.\n","categories":"","description":"","excerpt":"to_if_alone posts events when the from key is pressed alone.\nThe events are posted at the from key is released.\nExample The following json changes left_control to sending escape when left_control is …","ref":"/docs/json/complex-modifications-manipulator-definition/to-if-alone/","tags":"","title":"to_if_alone"},{"body":"set_variable defines and updates the variable value.\nTip set_variable is designed to use with variable_if and variable_unless conditions. { \"to\": [ { \"set_variable\": { \"name\": \"variable name\", \"value\": variable value, \"key_up_value\": variable value, \"type\": \"set\" } } ] } Name Required Description Available since name Required Target variable name. Karabiner-Elements 11.0.0 value Required | Optional Target variable value. Karabiner-Elements 11.0.0 key_up_value Optional A variable value when key is up Karabiner-Elements 14.12.6 type Optional “set” or “unset” Karabiner-Elements 14.99.2 Note: If key_up_value or type is specified, the value can be omitted.\nAvailable types of value Type Example value Available since integer 0,1,2,… Karabiner-Elements 11.0.0 boolean true, false Karabiner-Elements 14.4.20 string “layer1”, “layer2” Karabiner-Elements 14.4.20 Examples { \"set_variable\": { \"name\": \"mode_flag\", \"value\": 1, \"key_up_value\": 0 } } { \"set_variable\": { \"name\": \"mode_enabled\", \"value\": true } } { \"set_variable\": { \"name\": \"layer_name\", \"value\": \"layer1\" } } { \"set_variable\": { \"name\": \"my_flag\", \"type\": \"unset\" } } Confirm the current variable values You can see the current variable values by EventViewer \u003e Variables.\n","categories":"","description":"","excerpt":"set_variable defines and updates the variable value.\nTip set_variable is designed to use with variable_if and variable_unless conditions. { \"to\": [ { \"set_variable\": { \"name\": \"variable name\", …","ref":"/docs/json/complex-modifications-manipulator-definition/to/set-variable/","tags":"","title":"to.set_variable"},{"body":"It’s an issue of macOS, and unfortunately, Karabiner-Elements cannot avoid this issue.\nInstead, please change fn+number keys to function keys in Karabiner-Elements configuration.\nImport Map fn + number keys to function keys Enable Map fn + number keys to their corresponding function keys. You can use f1-f12 keys by fn+number keys. Note If you are using “Use all F1, F2, etc. keys as standard function keys.”, enable Map fn + number keys to their corresponding media control keys instead. Detail of the problem The fn key events are ignored by Touch Bar since the following facts.\nTouch Bar accepts the fn key event only from the build-in keyboard. The fn key events are sent from Karabiner’s virtual keyboard when Karabiner-Elements is running. Unfortunately, posting input events via own virtual keyboard is the only way to accomplish the stable input event modification.\nIn other words, we cannot post the fn key event through the built-in keyboard if we want to change key events stably.\n","categories":"","description":"","excerpt":"It’s an issue of macOS, and unfortunately, Karabiner-Elements cannot avoid this issue.\nInstead, please change fn+number keys to function keys in Karabiner-Elements configuration.\nImport Map fn + …","ref":"/docs/help/troubleshooting/touch-bar-function-keys/","tags":"","title":"Touch Bar does not change to f1-f12 when I press the fn key"},{"body":" Info This content is for older versions of Karabiner Elements. Prior to Karabiner-Elements 14.10.0, a lock indicator is shown on Karabiner-Elements and Karabiner-EventViewer icon.\nThese indicators show that these files are protected so that they cannot be deleted from Finder.\nWhy these files are protected This protection is intended to prevent incomplete uninstallation.\nKarabiner-Elements is a system-wide software, and files are installed in appropriate locations besides the Applications folder.\nTherefore, if you just put the application icon in Trash like a normal app uninstallation, some files will be left behind.\nThe file protection forces to use the built-in uninstaller and remove installed files properly at the uninstallation.\nAdvanced topic This file locking is achieved with schg and uchg flags.\nYou can unlock these files by running the following commands in Terminal. (Administrator password is required to run the commands.)\nsudo chflags nouchg,noschg /Applications/Karabiner-Elements.app sudo chflags nouchg,noschg /Applications/Karabiner-EventViewer.app In particular, if Full Disk Access rights have not been granted to Terminal, “Operation not permitted” error may be displayed. In this case, the safest solution is to grant App Management rights to Terminal.\n","categories":"","description":"","excerpt":" Info This content is for older versions of Karabiner Elements. Prior to Karabiner-Elements 14.10.0, a lock indicator is shown on Karabiner-Elements and Karabiner-EventViewer icon.\nThese indicators …","ref":"/docs/help/advanced-topics/lock-icon/","tags":"","title":"What is the lock indicator on Karabiner-Elements and Karabiner-EventViewer icon"},{"body":"set_notification_message sets or remove the notification message.\n{ \"to\": [ { \"set_notification_message\": { \"id\": \"identifier of the message\", \"text\": \"message text\" } } ] } Name Required Description id Required Specify an unique string for your notification message text Required Message body How to remove the notification message Set empty string to text to remove the notification message. Examples Show the notification message while you press right shift key.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"right_shift\", \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { // Show the notification message \"set_notification_message\": { \"id\": \"org.pqrs.notificaion_message_example\", \"text\": \"Hello World!\" } }, { \"key_code\": \"right_shift\" } ], \"to_after_key_up\": [ { // Hide the notification message \"set_notification_message\": { \"id\": \"org.pqrs.notificaion_message_example\", \"text\": \"\" } } ] } Important Do not forget to remove the notification message. ","categories":"","description":"","excerpt":"set_notification_message sets or remove the notification message.\n{ \"to\": [ { \"set_notification_message\": { \"id\": \"identifier of the message\", \"text\": \"message text\" } } ] } Name Required Description …","ref":"/docs/json/complex-modifications-manipulator-definition/to/set-notification-message/","tags":"","title":"to.set_notification_message"},{"body":"Karabiner-Elements provides a built-in event viewer named Karabiner-EventViewer. You can show keyboard and mouse events by using it.\nOpen Karabiner-EventViewer from Launchpad. Input events will be shown when you type keyboard on EventViewer or press pointing buttons on Mouse Area. ","categories":"","description":"","excerpt":"Karabiner-Elements provides a built-in event viewer named Karabiner-EventViewer. You can show keyboard and mouse events by using it.\nOpen Karabiner-EventViewer from Launchpad. Input events will be …","ref":"/docs/manual/operation/eventviewer/","tags":"","title":"Confirm the result of configuration (EventViewer)"},{"body":"It’s an issue of macOS, and unfortunately, Karabiner-Elements cannot avoid this issue.\nInstead, please change fn+escape to eject and use control+fn+escape (== control+eject) shortcut.\nImport Change escape key. Enable Change fn+escape to eject.\nYou can use control+fn+escape as control+eject. ","categories":"","description":"","excerpt":"It’s an issue of macOS, and unfortunately, Karabiner-Elements cannot avoid this issue.\nInstead, please change fn+escape to eject and use control+fn+escape (== control+eject) shortcut.\nImport Change …","ref":"/docs/help/troubleshooting/control-eject/","tags":"","title":"Control-eject shortcut does not work when Karabiner-Elements is running"},{"body":"You can disable MacBook built-in keyboard if external keyboards are connected.\nThis feature is useful when you put the external keybaord on top of the built-in keyboard.\nEnable Disable the built-in keyboard while this device is connected in Devices tab.\nConfigure the built-in keyboard detection Enable Treat as a built-in keyboard in Devices if your built-in keyboard is not recognized properly or you want to add a device that will be disabled,\n","categories":"","description":"","excerpt":"You can disable MacBook built-in keyboard if external keyboards are connected.\nThis feature is useful when you put the external keybaord on top of the built-in keyboard.\nEnable Disable the built-in …","ref":"/docs/manual/configuration/disable-built-in-keyboard/","tags":"","title":"Disable the built-in keyboard when external keyboard is connected"},{"body":"simultaneous_options adjust the simultaneous behavior.\nKey Value Description detect_key_down_uninterruptedly true or false Specify whether key_down detection is interrupted with unrelated events key_down_order insensitive, strict or strict_inverse Restriction of key_down order key_up_order insensitive, strict or strict_inverse Restriction of key_up order key_up_when any or all When key_up events are posted to_after_key_up An array of to event definitions Events will be posted when all from events are released detect_key_down_uninterruptedly If detect_key_down_uninterruptedly is true, Karabiner-Elements changes simultaneous events even if unrelated key down event exists between target events.\nFor example, when escape+3 -\u003e mission_control, escape,1,3 will be mission_control,1 if detect_key_down_uninterruptedly is true.\nThe default value is false.\nkey_down_order simultaneous checks the order of key_down events if key_down_order is specified and is not insensitive.\nFor example, this definition manipulates tab,q to mission_control and does not manipulate q,tab events.\n{ \"type\": \"basic\", \"from\": { \"simultaneous\": [ { \"key_code\": \"tab\" }, { \"key_code\": \"q\" } ], \"simultaneous_options\": { \"key_down_order\": \"strict\" }, \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"mission_control\" } ] } key_up_order simultaneous checks the order of key_up events if key_up_order is specified and is not insensitive.\nTip key_up_order is ignored if simultaneous_threshold_milliseconds is reached.\nYou should set a large value to simultaneous_threshold_milliseconds when you use key_up_order.\nFor example, this definition manipulates tab,q to mission_control if the tab key is released before the q key within 500 milliseconds.\nInput Output tab \u0026 q key_down — tab key_up mission_control key_down, mission_control key_up q key_up — Note Events will be posted just before the last from event’s key_up. { \"type\": \"basic\", \"parameters\": { \"basic.simultaneous_threshold_milliseconds\": 500 }, \"from\": { \"simultaneous\": [ { \"key_code\": \"tab\" }, { \"key_code\": \"q\" } ], \"simultaneous_options\": { \"key_up_order\": \"strict\" }, \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"mission_control\" } ] } key_up_when Specify when key_up events are posted.\nValue Description any Post key_up events when any key is released all Post key_up events when all keys are released to_after_key_up to_after_key_up will be posted when all from events are released.\nThis feature is typically used to clear mode flag variables when all from events are released.\nExample:\nMouse Keys Mode v4 json json generator Import ","categories":"","description":"","excerpt":"simultaneous_options adjust the simultaneous behavior.\nKey Value Description detect_key_down_uninterruptedly true or false Specify whether key_down detection is interrupted with unrelated events …","ref":"/docs/json/complex-modifications-manipulator-definition/from/simultaneous-options/","tags":"","title":"from.simultaneous_options"},{"body":"Karabiner-Elements will be started automatically at login after once you have run Karabiner-ELements.\nQuit Karabiner-Elements if you want to stop running Karabiner-Elements at login.\n","categories":"","description":"","excerpt":"Karabiner-Elements will be started automatically at login after once you have run Karabiner-ELements.\nQuit Karabiner-Elements if you want to stop running Karabiner-Elements at login.\n","ref":"/docs/help/how-to/disable-open-at-login/","tags":"","title":"How to disable running Karabiner-Elements at login"},{"body":"Change an event if/unless the current input source is the specified value.\nExample Switching input source between Japanese and English at tapping the left command key.\n[ { \"type\": \"basic\", \"from\": { \"key_code\": \"left_command\", \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"left_command\", \"lazy\": true } ], \"to_if_alone\": [ { \"key_code\": \"japanese_eisuu\" } ], \"to_if_held_down\": [ { \"key_code\": \"left_command\" } ], \"conditions\": [ { \"input_sources\": [ { \"language\": \"ja\" } ], \"type\": \"input_source_if\" } ], \"parameters\": { \"basic.to_if_held_down_threshold_milliseconds\": 100 } }, { \"type\": \"basic\", \"from\": { \"key_code\": \"left_command\", \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"left_command\", \"lazy\": true } ], \"to_if_alone\": [ { \"key_code\": \"japanese_kana\" } ], \"to_if_held_down\": [ { \"key_code\": \"left_command\" } ], \"conditions\": [ { \"input_sources\": [ { \"language\": \"en\" } ], \"type\": \"input_source_if\" } ], \"parameters\": { \"basic.to_if_held_down_threshold_milliseconds\": 100 } } ] Specification { \"type\": \"input_source_if\", \"input_sources\": [ { \"language\": \"language regex\", \"input_source_id\": \"input source id regex\", \"input_mode_id\": \"input mode id regex\" }, { \"language\": \"language regex\", \"input_source_id\": \"input source id regex\", \"input_mode_id\": \"input mode id regex\" }, ... ] } Name Required Description type Required \"input_source_if\" or \"input_source_unless\" input_sources Required Target input source definitions description Optional A human-readable comment input_sources input_sources is an array of objects.\nName Required Description language Optional The language regex such as \"^en$\", \"^ja$\" input_source_id Optional The input source id regex such as \"^com\\\\.apple\\\\.keylayout\\\\.US$\" input_mode_id Optional The input mode id regex such as \"^com\\\\.apple\\\\.inputmethod\\\\.Japanese\\\\.Hiragana$\" Multiple identifiers If you specify multiple identifiers (language, input_source_id or input_mode_id), these are joined by “and”.\nThe following condition is matched if language is “ja” and input_mode_id is “com.apple.inputmethod.Japanese.Hiragana”.\n{ \"type\": \"input_source_if\", \"input_sources\": [ { \"language\": \"^ja$\", \"input_mode_id\": \"^com\\\\.apple\\\\.inputmethod\\\\.Japanese\\\\.Hiragana$\" } ] } Multiple entries If you specify multiple entries at input_sources, conditions are joined by “or”.\nThe following condition is matched if language is “en” or “ja”.\n{ \"type\": \"input_source_if\", \"input_sources\": [ { \"language\": \"^en$\" }, { \"language\": \"^ja$\" } ] } Investigate the input source identifiers You can find the current input source identifiers by EventViewer \u003e Variables tab.\n{ \"input_source\": { \"input_mode_id\": \"com.apple.inputmethod.Japanese\", \"input_source_id\": \"com.google.inputmethod.Japanese.base\", \"language\": \"ja\" } } ","categories":"","description":"","excerpt":"Change an event if/unless the current input source is the specified value.\nExample Switching input source between Japanese and English at tapping the left command key.\n[ { \"type\": \"basic\", \"from\": { …","ref":"/docs/json/complex-modifications-manipulator-definition/conditions/input-source/","tags":"","title":"input_source_if, input_source_unless"},{"body":" Note Karabiner-Elements does not allow you including comments (// ... or /* ... */) in any json files. karabiner.json { \"global\": { \"check_for_updates_on_startup\": true, \"show_in_menu_bar\": true, \"show_profile_name_in_menu_bar\": false }, \"profiles\": [ { \"name\": \"Profile name\", \"selected\": true, \"simple_modifications\": [ ... ], \"fn_function_keys\": [ ... ], \"complex_modifications\": { \"parameters\": { ... }, \"rules\": [ ... ] }, \"virtual_hid_keyboard\": { \"keyboard_type\": \"ansi\", \"caps_lock_delay_milliseconds\": 0 }, \"devices\": [ ... ], \"parameters\": { ... } }, { \"name\": \"Profile name\", \"selected\": false, ... }, ... ] } complex_modifications in karabiner.json \u003e profiles { \"complex_modifications\": { \"parameters\": { ... }, \"rules\": [ { \"description\": \"This description is shown in Settings.\", \"manipulators\": [ { \"type\": \"basic\", \"from\": from event definition, \"to\": [ to event definition, to event definition, ... ], \"to_if_alone\": [ to event definition, to event definition, ... ], \"to_if_held_down\": [ to event definition, to event definition, ... ], \"to_after_key_up\": [ to event definition, to event definition, ... ], \"to_delayed_action\": { \"to_if_invoked\": [ to event definition, to event definition, ... ], \"to_if_canceled\": [ to event definition, to event definition, ... ] }, \"conditions\": [ condition definition, condition definition, ... ], \"parameters\": { ... }, \"description\": \"Optional description for human\" }, { \"type\": \"basic\", ... }, ... ] }, { \"description\": \"...\", \"manipulators\": [ ... ] }, ... ] } } custom *.json file in ~/config/karabiner/assets/complex_modifications Note Adding a custom .json file allows for enabling and disabling rules/complex modifications through the UI. { \"title\": \"Title for the list of rules/complex modifications.\", \"rules\": [ { \"description\": \"This description is shown in Settings.\", \"manipulators\": [ { \"type\": \"basic\", \"from\": from event definition, \"to\": [ to event definition, to event definition, ... ], \"to_if_alone\": [ to event definition, to event definition, ... ], \"to_if_held_down\": [ to event definition, to event definition, ... ], \"to_after_key_up\": [ to event definition, to event definition, ... ], \"to_delayed_action\": { \"to_if_invoked\": [ to event definition, to event definition, ... ], \"to_if_canceled\": [ to event definition, to event definition, ... ] }, \"conditions\": [ condition definition, condition definition, ... ], \"parameters\": { ... }, \"description\": \"Optional description for human\" }, { \"type\": \"basic\", ... }, ... ] }, { \"description\": \"...\", \"manipulators\": [ ... ] }, ... ] } ","categories":"","description":"","excerpt":" Note Karabiner-Elements does not allow you including comments (// ... or /* ... */) in any json files. karabiner.json { \"global\": { \"check_for_updates_on_startup\": true, \"show_in_menu_bar\": true, …","ref":"/docs/json/root-data-structure/","tags":"","title":"karabiner.json data structure"},{"body":"Karabiner-MultitouchExtension allows you to change keys only when your finger is on the trackpad.\nNote Karabiner-MultitouchExtension is available since Karabiner-Elements 12.6.9 Related Complex Modifications examples Multitouch Vi Mode Multitouch Diamond Cursor Multitouch Mouse Buttons ThumbSense MultitouchExtension usage Open MultitouchExtension app from Karabiner-Elements Settings \u003e Misc. Enable “Start at login” on MultitouchExtension Preferences. Adjust the effective area of the trackpad. Tip If you hid Karabiner-MultitouchExtension icon in Dock, press “Open MultitouchExtension app” button on Preferences \u003e Misc to open Karabiner-MultitouchExtension Preferences. How to integrate MultitouchExtension to your complex modifications See karabiner.json reference manual\n","categories":"","description":"","excerpt":"Karabiner-MultitouchExtension allows you to change keys only when your finger is on the trackpad.\nNote Karabiner-MultitouchExtension is available since Karabiner-Elements 12.6.9 Related Complex …","ref":"/docs/manual/misc/multitouch-extension/","tags":"","title":"MultitouchExtension"},{"body":"to_if_held_down posts events when the from key is held down.\nNote If to events are specified, key_up event of to is sent before to_if_held_down events are posted. Example The following json changes the escape key to open Alfred when the escape key is held down.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"escape\", \"modifiers\": { \"optional\": [\"caps_lock\"] } }, \"parameters\": { \"basic.to_if_alone_timeout_milliseconds\": 250, \"basic.to_if_held_down_threshold_milliseconds\": 250 }, \"to_if_alone\": [ { \"key_code\": \"escape\" } ], \"to_if_held_down\": [ { \"shell_command\": \"open -a 'Alfred 4.app'\" } ] } Parameter You can adjust the threshold of holding down periods by parameters \u003e basic.to_if_held_down_threshold_milliseconds like the above example.\n","categories":"","description":"","excerpt":"to_if_held_down posts events when the from key is held down.\nNote If to events are specified, key_up event of to is sent before to_if_held_down events are posted. Example The following json changes …","ref":"/docs/json/complex-modifications-manipulator-definition/to-if-held-down/","tags":"","title":"to_if_held_down"},{"body":"Move mouse pointer and scroll by mouse_key.\n{ \"to\": [ { \"mouse_key\": { \"x\": speed, \"y\": speed, \"vertical_wheel\": speed, \"horizontal_wheel\": speed, \"speed_multiplier\": 1.0 } } ] } Name Required Description x Optional Move left (x \u003c 0) or right (x \u003e 0) y Optional Move up (y \u003c 0) or down (y \u003e 0) vertical_wheel Optional Scroll up (vertical_wheel \u003c 0) or down (vertical_wheel \u003e 0) horizontal_wheel Optional Scroll left (horizontal_wheel \u003e 0) or right (horizontal_wheel \u003c 0) speed_multiplier Optional Multiply mouse keys speed while this key is hold down Note Speed and scroll direction depend on System Settings \u003e Mouse configuration. Examples json Move left { \"mouse_key\": { \"x\": -1536 } } Move right { \"mouse_key\": { \"x\": 1536 } } Move up { \"mouse_key\": { \"y\": -1536 } } Move down { \"mouse_key\": { \"y\": 1536 } } Scroll left { \"mouse_key\": { \"horizontal_wheel\": 32 } } Scroll right { \"mouse_key\": { \"horizontal_wheel\": -32 } } Scroll up { \"mouse_key\": { \"vertical_wheel\": -32 } } Scroll down { \"mouse_key\": { \"vertical_wheel\": 32 } } Complete json examples Mouse keys (simple) Mouse Keys Mode v4 ","categories":"","description":"","excerpt":"Move mouse pointer and scroll by mouse_key.\n{ \"to\": [ { \"mouse_key\": { \"x\": speed, \"y\": speed, \"vertical_wheel\": speed, \"horizontal_wheel\": speed, \"speed_multiplier\": 1.0 } } ] } Name Required …","ref":"/docs/json/complex-modifications-manipulator-definition/to/mouse-key/","tags":"","title":"to.mouse_key"},{"body":"It’s a hardware limitation of your keyboard called “two-key rollover” if you cannot use some three key combinations. (e.g., physical left command key + right command key + m)\nThere are two way to avoid the rollover problem.\nUse another keyboard which is N-key rollover. Use other key combinations. ","categories":"","description":"","excerpt":"It’s a hardware limitation of your keyboard called “two-key rollover” if you cannot use some three key combinations. (e.g., physical left command key + right command key + m)\nThere are two way to …","ref":"/docs/help/troubleshooting/cannot-use-some-key-combination/","tags":"","title":"Cannot use some three key combinations (key event is not fired)"},{"body":"sticky_modifier changes a key to a sticky modifier key.\n{ \"to\": [ { \"sticky_modifier\": { \"{modifier_name}\": \"on | off | toggle\" } } ] } Name Required Description {modifier_name} Optional - on always activates a sticky modifier.\n- off is vice versa.\n- toggle toggles a sticky modifier. toggle is suitable for most cases. Supported modifiers left_control left_shift left_option left_command right_control right_shift right_option right_command fn Examples { \"to\": [ { \"sticky_modifier\": { \"right_option\": \"toggle\" } } ] } Note You have to specify only one modifier.\nIf you want to activate multiple sticky modifiers, put multiple sticky_modifier as follows.\n{ \"to\": [ { \"sticky_modifier\": { \"left_control\": \"toggle\" } }, { \"sticky_modifier\": { \"left_shift\": \"toggle\" } } ] } ","categories":"","description":"","excerpt":"sticky_modifier changes a key to a sticky modifier key.\n{ \"to\": [ { \"sticky_modifier\": { \"{modifier_name}\": \"on | off | toggle\" } } ] } Name Required Description {modifier_name} Optional - on always …","ref":"/docs/json/complex-modifications-manipulator-definition/to/sticky-modifier/","tags":"","title":"to.sticky_modifier"},{"body":"software_function triggers a function that is implemented by software.\ncg_event_double_click Send double click event by software. set_mouse_cursor_position Move the mouse cursor to the specified point. iokit_power_management_sleep_system Causes an immediate system sleep. Table of Contents ","categories":"","description":"","excerpt":"software_function triggers a function that is implemented by software.\ncg_event_double_click Send double click event by software. set_mouse_cursor_position Move the mouse cursor to the specified …","ref":"/docs/json/complex-modifications-manipulator-definition/to/software_function/","tags":"","title":"to.software_function"},{"body":"If the following error message is appeared in log, your home directory owner ship is not valid.\n[warning] [grabber] /Users/.../karabiner.json is not owned by a valid user. The cause is that you are using an external storage and locating your home directory into the volume.\nYou have to enable ownership on the external volume by the following command in Terminal.app.\nsudo diskutil enableOwnership disk99999s99999 (Replace disk99999s99999 with your disk identifier which you can find by diskutil list command.)\n","categories":"","description":"","excerpt":"If the following error message is appeared in log, your home directory owner ship is not valid.\n[warning] [grabber] /Users/.../karabiner.json is not owned by a valid user. The cause is that you are …","ref":"/docs/help/troubleshooting/json-owner-is-invalid/","tags":"","title":"\"karabiner.json is not owned by a valid user\" error message in log"},{"body":"Karabiner-Elements provides a command line interface which provides the following functions.\nSwitch a profile by name. Show current profile name. Show all profile names. Set variables which are used in complex modifications. Copy the current profile to system default profile. (Administrator privilege is required.) Remove the system default profile. (Administrator privilege is required.) Lint complex_modifications.json. Display version. Usage Show help Run the following command in terminal.\n'/Library/Application Support/org.pqrs/Karabiner-Elements/bin/karabiner_cli' Result:\nA command line utility of Karabiner-Elements. Usage: karabiner_cli [OPTION...] --select-profile arg Select a profile by name. --show-current-profile-name Show current profile name --list-profile-names Show all profile names --set-variables arg Json string: {[key: string]: number|boolean|string} --copy-current-profile-to-system-default-profile Copy the current profile to system default profile. --remove-system-default-profile Remove the system default profile. --lint-complex-modifications complex_modifications.json Check complex_modifications.json --version Displays version. --version-number Displays version_number. --help Print help. Examples: karabiner_cli --select-profile 'Default profile' karabiner_cli --show-current-profile-name karabiner_cli --list-profile-names karabiner_cli --set-variables '{\"cli_flag1\":1, \"cli_flag2\":2}' Examples Switch profile Run the following command in terminal.\n'/Library/Application Support/org.pqrs/Karabiner-Elements/bin/karabiner_cli' --select-profile 'Default profile' Show current profile name Run the following command in terminal.\n'/Library/Application Support/org.pqrs/Karabiner-Elements/bin/karabiner_cli' --show-current-profile-name Show all profile names '/Library/Application Support/org.pqrs/Karabiner-Elements/bin/karabiner_cli' --list-profile-names ","categories":"","description":"","excerpt":"Karabiner-Elements provides a command line interface which provides the following functions.\nSwitch a profile by name. Show current profile name. Show all profile names. Set variables which are used …","ref":"/docs/manual/misc/command-line-interface/","tags":"","title":"Command line interface"},{"body":"\"manipulators\": [ { \"type\": \"basic\", \"from\": {...}, \"to\": [...], \"to_if_alone\": [...], \"to_if_held_down\": [...], \"to_after_key_up\": [...], \"to_delayed_action\": { \"to_if_invoked\": [...], \"to_if_canceled\": [...], }, \"conditions\": [...], \"parameters\": {...}, \"description\": \"Optional description for human\" }, ... ] Name Required Description type Required \"basic\" is specified from Required The name of key code, consumer key code or pointing button which you want to change to Optional Events which are sent when you press from key to_if_alone Optional Events which are sent when you press from key alone to_if_held_down Optional Events which are sent when you hold down from key to_after_key_up Optional Events which are sent after you release from key to_delayed_action Optional Events which are sent after 500 milliseconds at you press from key conditions Optional Manipulator is applied only if condition is matched (e.g., the frontmost application) parameters Optional Override parameters such as to_if_alone_timeout_milliseconds description Optional A human-readable comment Detail from event definition to event definition to_if_alone to_if_held_down to_after_key_up to_delayed_action conditions Other manipulators Manipulators which type is not \"basic\".\nmouse_motion_to_scroll Table of Contents ","categories":"","description":"","excerpt":"\"manipulators\": [ { \"type\": \"basic\", \"from\": {...}, \"to\": [...], \"to_if_alone\": [...], \"to_if_held_down\": [...], \"to_after_key_up\": [...], \"to_delayed_action\": { \"to_if_invoked\": [...], …","ref":"/docs/json/complex-modifications-manipulator-definition/","tags":"","title":"complex_modifications manipulator definition"},{"body":"You can switch profiles from menu bar. Manage profiles You can manage profiles from Profiles tab.\nPress Add new profile button to add new profile.\n","categories":"","description":"","excerpt":"You can switch profiles from menu bar. Manage profiles You can manage profiles from Profiles tab.\nPress Add new profile button to add new profile.\n","ref":"/docs/manual/operation/profiles/","tags":"","title":"Manage profiles"},{"body":"You can change the keyboard type (ANSI, ISO, JIS) from Virtual Keyboard tab.\nThe keyboard type is tied to the country code due to the macOS specification. And we have to log out to apply the keyboard type changes.\nSo, we recommend to assign each keyboard types to country code 0,1,2. And then, choose the country code when you want to change the current keyboard type.\nNote We have to log out after the keyboard type (ANSI, ISO, JIS) is changed to apply the changes.\nRelated articles Troubleshooting \u003e Input symbols are different from the key code name on non-ANSI keyboards ","categories":"","description":"","excerpt":"You can change the keyboard type (ANSI, ISO, JIS) from Virtual Keyboard tab.\nThe keyboard type is tied to the country code due to the macOS specification. And we have to log out to apply the keyboard …","ref":"/docs/manual/configuration/configure-keyboard-type/","tags":"","title":"Set keyboard type"},{"body":"to_after_key_up posts events when the from key is released.\nTip to_after_key_up is typically used to:\nUnset variables using set_variable Used with to_if_held_down and to.halt in order to define fallback behavior. Example The following json changes holding tab key to mission_control.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"tab\" }, \"to_after_key_up\": [ { \"key_code\": \"tab\" } ], \"to_if_held_down\": [ { \"key_code\": \"mission_control\", \"halt\": true } ] } ","categories":"","description":"","excerpt":"to_after_key_up posts events when the from key is released.\nTip to_after_key_up is typically used to:\nUnset variables using set_variable Used with to_if_held_down and to.halt in order to define …","ref":"/docs/json/complex-modifications-manipulator-definition/to-after-key-up/","tags":"","title":"to_after_key_up"},{"body":"to.modifiers is an array of the following strings.\nName Description caps_lock — left_command — left_control — left_option — left_shift — right_command — right_control — right_option — right_shift — fn — command Alias of left_command control Alias of left_control option Alias of left_option shift Alias of left_shift left_alt Alias of left_option (available since Karabiner-Elements 12.3.0) left_gui Alias of left_command (available since Karabiner-Elements 12.3.0) right_alt Alias of right_option (available since Karabiner-Elements 12.3.0) right_gui Alias of right_command (available since Karabiner-Elements 12.3.0) ","categories":"","description":"","excerpt":"to.modifiers is an array of the following strings.\nName Description caps_lock — left_command — left_control — left_option — left_shift — right_command — right_control — right_option — right_shift — fn …","ref":"/docs/json/complex-modifications-manipulator-definition/to/modifiers/","tags":"","title":"to.modifiers"},{"body":"Change an event if/unless the variable is the specified value.\nExample Change right_shift x2 to mission_control Virtual modifier Specification Tip variable_if and variable_unless are designed to use with set_variable. { \"type\": \"variable_if\", \"name\": \"variable name\", \"value\": variable value } Name Required Description type Required \"variable_if\" or \"variable_unless\". name Required Target variable name. value Required Target variable value. description Optional A human-readable comment Available types of value Type Example value Available since integer 0,1,2,… Karabiner-Elements 11.0.0 boolean true, false Karabiner-Elements 14.4.20 string “layer1”, “layer2” Karabiner-Elements 14.4.20 Comparison between different types Whenever the type of value is different, it is treated as having different contents.\n1 != true true != \"true\" Default value If the variable is not set to a value, the value is treated as 0. Confirm the current variable values You can see the current variable values by EventViewer \u003e Variables.\n","categories":"","description":"","excerpt":"Change an event if/unless the variable is the specified value.\nExample Change right_shift x2 to mission_control Virtual modifier Specification Tip variable_if and variable_unless are designed to use …","ref":"/docs/json/complex-modifications-manipulator-definition/conditions/variable/","tags":"","title":"variable_if, variable_unless"},{"body":"Karabiner-Elements shows an icon in menu bar which provides the following functions:\nSwitch profiles. Open Settings. Open EventViewer. Quit Karabiner-Elements. If you want to hide it, turn off “Show icon in menu bar” on Settings \u003e Misc tab.\n","categories":"","description":"","excerpt":"Karabiner-Elements shows an icon in menu bar which provides the following functions:\nSwitch profiles. Open Settings. Open EventViewer. Quit Karabiner-Elements. If you want to hide it, turn off “Show …","ref":"/docs/manual/configuration/configure-menu-bar-icon/","tags":"","title":"Configure icon in menu bar"},{"body":"Change an event if/unless the event is already changed by other manipulators.\nExample Change tab key to return_or_enter if the tab key is the physical tab key. (If the tab key is the result of modifying another key by simple modification, the key is ignored.)\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"tab\", \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"return_or_enter\" } ], \"conditions\": [ { \"type\": \"event_changed_if\", \"value\": false } ] } Specification { \"type\": \"event_changed_if\", \"value\": true } Name Required Description type Required \"event_changed_if\" or \"event_changed_unless\" value Required true or false description Optional A human-readable comment Tip event_changed_unless is designed to prevent Function Keys Modifications from changing fx keys which are changed in Complex Modifications (e.g., Change command+e to f2).\nIf you use event_changed_if or event_changed_unless in Complex Modifications, your rule is ignored for keys which are changed in Simple Modifications.\n","categories":"","description":"","excerpt":"Change an event if/unless the event is already changed by other manipulators.\nExample Change tab key to return_or_enter if the tab key is the physical tab key. (If the tab key is the result of …","ref":"/docs/json/complex-modifications-manipulator-definition/conditions/event-changed/","tags":"","title":"event_changed_if, event_changed_unless"},{"body":" Note This page is for macOS 10.15 Catalina, not macOS 11 Big Sur or later. “.Karabiner-VirtualHIDDevice-Manager” is usually shown in Security \u0026 Privacy System Preferences when macOS requires your approval.\nHowever, “Placeholder Developer” will be shown due to a macOS issue if you meet all of the following criteria:\nYou are using macOS Catalina (10.15) Multiple system software are waiting your approval. Workarounds In this case, you can choose one of the following three options to use Karabiner-Elements:\nUpgrade to macOS Big Sur (11.0) or later. Downgrade to Karabiner-Elements v12.10.0.\nDownload the package from the above page, and then re-install Karabiner-Elements from the downloaded package. Allow “Placeholder Developer”. Info: This issue is solved with macOS Big Sur (11.0) The name is shown properly on macOS Big Sur.\n","categories":"","description":"","excerpt":" Note This page is for macOS 10.15 Catalina, not macOS 11 Big Sur or later. “.Karabiner-VirtualHIDDevice-Manager” is usually shown in Security \u0026 Privacy System Preferences when macOS requires your …","ref":"/docs/help/troubleshooting/placeholder-developer/","tags":"","title":"Placeholder Developer is shown in Security \u0026 Privacy System Preferences"},{"body":"You can confirm log messages on Log tab.\nAdvanced topic The log files are placed at:\nSystem logs\n/var/log/karabiner/grabber.log /var/log/karabiner/observer.log /var/log/karabiner/virtual_hid_device_service.log User logs\n~/.local/share/karabiner/log/console_user_server.log ~/.local/share/karabiner/log/grabber_agent.log ~/.local/share/karabiner/log/observer_agent.log /var/log/karabiner/session_monitor.{uid}.log ","categories":"","description":"","excerpt":"You can confirm log messages on Log tab.\nAdvanced topic The log files are placed at:\nSystem logs\n/var/log/karabiner/grabber.log /var/log/karabiner/observer.log …","ref":"/docs/manual/operation/log/","tags":"","title":"Show log messages"},{"body":"Karabiner-Elements stores configuration to a json file which is located ~/.config/karabiner/karabiner.json\nAbout symbolic link If you want to move karabiner.json to another place and make symbolic link, make a symbolic link to ~/.config/karabiner directory instead of karabiner.json.\nWarning Do not make a symlink to karabiner.json directly.\nKarabiner-Elements will fail to detect the configuration file update and fail to reload the configuration if karabiner.json is a symbolic link.\nMaking symbolic link example The following command allows you to put karabiner.json on ~/Dropbox/private.\nmv ~/.config/karabiner ~/Dropbox/private ln -s ~/Dropbox/private/karabiner ~/.config Note You have to restart karabiner_console_user_server process by the following command after you made a symlink in order to tell Karabiner-Elements that the parent directory is changed.\nlaunchctl kickstart -k gui/`id -u`/org.pqrs.karabiner.karabiner_console_user_server ","categories":"","description":"","excerpt":"Karabiner-Elements stores configuration to a json file which is located ~/.config/karabiner/karabiner.json\nAbout symbolic link If you want to move karabiner.json to another place and make symbolic …","ref":"/docs/manual/misc/configuration-file-path/","tags":"","title":"The location of the configuration file"},{"body":"to_delayed_action posts events after 500 milliseconds from the from key is pressed.\nto_delayed_action.to_if_invoked An array of to events that will be sent if no other key is pressed after the from key is pressed. to_delayed_action.to_if_canceled An array of to events that will be sent if another key is pressed after the from key is pressed before to_delayed_action.to_if_invoked is sent. Tip to_delayed_action is typically used to:\nDouble tap key (e.g., change right_shift x2) 2 stroke keys such as C-x of Emacs Mode. Example The following json provide Quit application by pressing command-q twice.\n[ { \"type\": \"basic\", \"conditions\": [ { \"type\": \"variable_if\", \"name\": \"command-q\", \"value\": 1 } ], \"from\": { \"key_code\": \"q\", \"modifiers\": { \"mandatory\": [\"command\"], \"optional\": [\"caps_lock\"] } }, \"to\": [ { \"key_code\": \"q\", \"modifiers\": \"left_command\" } ] }, { \"type\": \"basic\", \"from\": { \"key_code\": \"q\", \"modifiers\": { \"mandatory\": [\"command\"], \"optional\": [\"caps_lock\"] } }, \"to\": [ { \"set_variable\": { \"name\": \"command-q\", \"value\": 1 } } ], \"to_delayed_action\": { \"to_if_invoked\": [ { \"set_variable\": { \"name\": \"command-q\", \"value\": 0 } } ], \"to_if_canceled\": [ { \"set_variable\": { \"name\": \"command-q\", \"value\": 0 } } ] } } ] Parameters You can adjust the milliseconds invoking to_delayed_action by parameters \u003e basic.to_delayed_action_delay_milliseconds as follows.\n{ \"type\": \"basic\", \"from\": ..., \"to_delayed_action\": ..., \"parameters\": { \"basic.to_delayed_action_delay_milliseconds\": 1000 } } ","categories":"","description":"","excerpt":"to_delayed_action posts events after 500 milliseconds from the from key is pressed.\nto_delayed_action.to_if_invoked An array of to events that will be sent if no other key is pressed after the from …","ref":"/docs/json/complex-modifications-manipulator-definition/to-delayed-action/","tags":"","title":"to_delayed_action"},{"body":"to.lazy is true or false. The default value is false.\nIf to.lazy is true and to.key_code is modifier flag such as \"key_code\": \"left_shift\", the to.key_code acts as lazy modifier.\nThe lazy modifier does not send own key events until another key is pressed together.\nTip The lazy modifier is designed using with to_if_alone or key combinations such as changing left_control + h to delete_or_backspace in order to suppress unnecessary modifier key events. Example The following json changes:\nleft_control to the lazy left control left_control + m to return_or_enter Behavior of the json:\nThe left_control key event will not be sent when you press left_control alone. Only the return_or_enter key event will be sent when you press left_control + m. You can use left_control for other keys such as left_control + a, left_control + b, etc. [ { \"type\": \"basic\", \"from\": { \"key_code\": \"left_control\" }, \"to\": [ { \"key_code\": \"left_control\", \"lazy\": true } ] }, { \"type\": \"basic\", \"from\": { \"key_code\": \"m\", \"modifiers\": { \"mandatory\": [\"left_control\"], \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"return_or_enter\" } ] } ] ","categories":"","description":"","excerpt":"to.lazy is true or false. The default value is false.\nIf to.lazy is true and to.key_code is modifier flag such as \"key_code\": \"left_shift\", the to.key_code acts as lazy modifier.\nThe lazy modifier …","ref":"/docs/json/complex-modifications-manipulator-definition/to/lazy/","tags":"","title":"to.lazy"},{"body":"You can change the icons that appear in the Finder, Launchpad, Dock, etc from Settings \u003e UI.\nNote The icon in Dock will not reflect changes while the application is open. So, you should close and reopen the application to update the icon in Dock. ","categories":"","description":"","excerpt":"You can change the icons that appear in the Finder, Launchpad, Dock, etc from Settings \u003e UI.\nNote The icon in Dock will not reflect changes while the application is open. So, you should close and …","ref":"/docs/manual/misc/change-app-icon/","tags":"","title":"Change app icon"},{"body":"Privacy Security and privacy protection is one of the most important points of Karabiner-Elements architecture design.\nOf course, Karabiner-Elements does not collect any of your input data, your configuration data, nor your usage statistics.\nData not collected Karabiner-Elements does not transmit your data externally. The following data is never transmitted outside your Mac:\nYour keystrokes Your configuration data Your usage statistics And all other data except Karabiner-Elements version information. About Input Monitoring Karabiner-Elements exclusively receives input events from your keyboard, and then modifies them. To do this, Karabiner-Elements requires your Input Monitoring permissions approval.\nKeystrokes captured with this privilege are processed entirely on your Mac. And because the process is protected by administrative privileges, keystrokes cannot be intercepted at by other applications on your Mac.\nSpecifically, the processes with administrative privileges are as follows:\nkarabiner_grabber: This is the most core process in Karabiner-Elements that captures and modifies keystrokes. karabiner_observer: This process monitors input events on non-capturing devices and controls karabiner_grabber so that it does not start capturing while the very keystrokes are being made. Note: Karabiner-EventViewer operates with lower privileges than karabiner_grabber and karabiner_observer. Since it runs with user privileges, it cannot receive keystrokes during password inputs or similar actions when Secure Keyboard Entry is enabled.\nInput event manipulation After capturing keystrokes, the karabiner_grabber process modifies input events based on user settings. Modifying input events is also performed with security considerations in mind.\nTo prevent the addition of malicious input from other applications, karabiner_grabber performs closed operations within the process, which has administrative privileges. And the karabiner_grabber process does not knowingly alter, insert or manipulate any keystrokes other than as configured and expected by the user.\nNote: Some combinations, such as fn+arrow keys, are implicitly changed. For a list, please see Implicit behavior.\nUser data and files Karabiner-Elements and any bundled softwares, e.g., EventViewer, do not access or modify user data and files, except in the following data:\nUser files and data referenced by Karabiner-Elements:\nConfiguration files specific to the application. The keyboard type configuration (ANSI, ISO, JIS) in the system settings. The “Use F1, F2, etc. keys as standard function keys” configuration in the system settings. About karabiner_machine_identifier Since Karabiner-Elements v14.99.2, a unique random ID called karabiner_machine_identifier is generated for each machine during Karabiner-Elements installation. This ID may be included in the configuration file karabiner.json when machine-specific settings are made. For instance, when the Multitouch Extension is enabled, the following content is added to karabiner.json, and the string starting with krbn- is the karabiner_machine_identifier.\nThis string is completely random and does not contain any unique information about the user or the machine. In other words, this ID is not linked to information like your Apple ID or Mac’s serial number. Therefore, it is a safe ID to share with others, and there is no need to mask it when you share karabiner.json with others.\nOf course, Karabiner-Elements never collect this ID.\nTechnical Information The karabiner_machine_identifier is in the format krbn-{UUID v4}.\nThe generated ID is saved in /Library/Application Support/org.pqrs/tmp/karabiner_machine_identifier.json as the following forms.\n{ \"karabiner_machine_identifier\": \"krbn-818632bf-2a88-4ac0-ad0b-4524721c217b\" } Data being collected The only data we are collecting is Karabiner-Elements version information.\nWe use the data only for checking updates, and we do not share these data with others. How we receive the data The version information will be sent in order to check updates when automatic update is enabled, or when you press the update button manually.\nThe URLs to send the version information are as follows:\nhttps://appcast.pqrs.org/karabiner-elements-appcast.xml https://appcast.pqrs.org/karabiner-elements-appcast-devel.xml You can change the automatic update setting in Update tab.\nDetail appcast.pqrs.org receives the version information like follows:\n150.249.243.141 - - [13/Feb/2021:18:37:14 +0900] \"GET /karabiner-elements-appcast.xml HTTP/2.0\" 200 2389 \"-\" \"Karabiner-Elements/13.3.0 Sparkle/1.24.0\" \"-\" 150.249.243.141 - - [13/Feb/2021:19:26:15 +0900] \"GET /karabiner-elements-appcast-devel.xml HTTP/2.0\" 200 740 \"-\" \"Karabiner-Elements/13.3.0 Sparkle/1.24.0\" \"-\" The received data contains:\nName Example Access source IP address 150.249.243.141 Access time 13/Feb/2021:18:37:14 +0900 Karabiner-Elements version Karabiner-Elements/13.3.0 Sparkle/1.24.0 Related documents Security ","categories":"","description":"","excerpt":"Privacy Security and privacy protection is one of the most important points of Karabiner-Elements architecture design.\nOf course, Karabiner-Elements does not collect any of your input data, your …","ref":"/docs/privacy/","tags":"","title":"Privacy"},{"body":"If you are using old Karabiner-Elements (12.x.x or earlier) on macOS Catalina or later, the following alert will be shown.\nPlease upgrade Karabiner-Elements 13.0.0 or later.\n","categories":"","description":"","excerpt":"If you are using old Karabiner-Elements (12.x.x or earlier) on macOS Catalina or later, the following alert will be shown.\nPlease upgrade Karabiner-Elements 13.0.0 or later.\n","ref":"/docs/manual/misc/legacy-system-extension/","tags":"","title":"About \"Legacy System Extension\" alert"},{"body":"Karabiner-Elements has a setting to disable caps lock LED control.\nIf your caps lock LED is not working properly, this setting may be enabled, so check the Manipulate caps lock LED setting in the Devices tab.\n","categories":"","description":"","excerpt":"Karabiner-Elements has a setting to disable caps lock LED control.\nIf your caps lock LED is not working properly, this setting may be enabled, so check the Manipulate caps lock LED setting in the …","ref":"/docs/help/troubleshooting/caps-lock-led-not-working/","tags":"","title":"Caps Lock LED not working"},{"body":"Reporting Bugs, Feature requests Please post an issue to GitHub.\nKarabiner-Elements KE-complex_modifications (About complex modifications) Required information with bug reports Please fill your information when you send bug reports:\nRequired information macOS version: Karabiner version:\n(You can confirm the version in “Update” tab in Karabiner Settings.) Your Mac hardware: Your keyboard hardware: Example:\nmacOS version: macOS 14.1.2 Karabiner version: Karabiner-Elements 14.13.0 Your Mac hardware: M2 MacBook Air Your keyboard hardware: Das Keyboard 4 Professional for Mac Mechanical Keyboard Other Send a message to author of Karabiner-Elements.\nNote I’m sorry I cannot spend enough time to reply for all mails since I’m receiving a lot mails.\nGitHub is suitable place to post it unless you have a private question. ","categories":"","description":"","excerpt":"Reporting Bugs, Feature requests Please post an issue to GitHub.\nKarabiner-Elements KE-complex_modifications (About complex modifications) Required information with bug reports Please fill your …","ref":"/docs/contact/","tags":"","title":"Contact"},{"body":"You can export and import configuration by copying karabiner.json file to another machine.\nExport Open config folder from Karabiner-Elements Settings \u003e Misc. Configuration folder will be opened by Finder. Copy the karabiner.json file. Import Open config folder from Karabiner-Elements Settings \u003e Misc. Replace karabiner.json with the exported file. (The configuration file will be reloaded automatically.) ","categories":"","description":"","excerpt":"You can export and import configuration by copying karabiner.json file to another machine.\nExport Open config folder from Karabiner-Elements Settings \u003e Misc. Configuration folder will be opened by …","ref":"/docs/manual/operation/export/","tags":"","title":"Export and import configuration"},{"body":"Karabiner-Elements configuration generators:\nGokuRakuJoudo Goku generates karabiner.json from well designed edn format file. Karabiner Complex Modification The web UI for creating json of complex modification rules. Karabiner::CompModGenerator Raku module for easily bulk generating and regenerating complex modification from pre-defined templates. Jsonnet A data templating language as a simple extension of JSON to generate config data with the benefit to organize, simplify, unify, and manage sprawling configurations. karabiner.ts Write complex modification rules in TypeScript with strong typing. ","categories":"","description":"","excerpt":"Karabiner-Elements configuration generators:\nGokuRakuJoudo Goku generates karabiner.json from well designed edn format file. Karabiner Complex Modification The web UI for creating json of complex …","ref":"/docs/json/external-json-generators/","tags":"","title":"External JSON generators"},{"body":"to.repeat is true or false. The default value is true.\nThe key repeating will be suppressed if to.repeat is false.\nNote You have to set repeat in the last to event as follows if you have multiple to events and want to set to.repeat false.\n{ \"to\": [ { \"key_code\": \"h\" }, { \"key_code\": \"e\" }, { \"key_code\": \"l\" }, { \"key_code\": \"l\" }, { \"key_code\": \"o\", \"repeat\": false } ] } Tip to.repeat affects key_up event sending timing as follows.\nIf to.repeat is true: key_up event is sent when you release the key. If to.repeat is false: key_down and key_up events are sent when you press the key. ","categories":"","description":"","excerpt":"to.repeat is true or false. The default value is true.\nThe key repeating will be suppressed if to.repeat is false.\nNote You have to set repeat in the last to event as follows if you have multiple to …","ref":"/docs/json/complex-modifications-manipulator-definition/to/repeat/","tags":"","title":"to.repeat"},{"body":"There are several settings that cannot be enabled by default in the GUI to prevent improper configuration which breaks macOS operation.\nAlthough never recommended, enabling Unsafe Configuration from the Pro tab allows you the following operations.\nIf you want to enable the unsafe configuration, remember how to start up your Mac in safe mode. You can restore the settings in safe mode even if you make a mistake.\nHow to enable unsafe configuration Enabled operations Allow to modify Apple pointing devices Before:\nAfter:\nAllow to change the mouse button 1 It is possible to change the left click.\n","categories":"","description":"","excerpt":"There are several settings that cannot be enabled by default in the GUI to prevent improper configuration which breaks macOS operation.\nAlthough never recommended, enabling Unsafe Configuration from …","ref":"/docs/manual/operation/about-unsafe-configuration/","tags":"","title":"About Unsafe Configuration"},{"body":"If you face a problem and you want to revert previous version, please downgrade Karabiner-Elements as follows.\nUninstall Karabiner-Elements from uninstaller. Download a previous version from here. Install again. Advanced topic The first uninstallation is required to remove the virtual driver. Since virtual drivers cannot be directly downgraded, if you want to install an older version, you need to remove a newer version beforehand. ","categories":"","description":"","excerpt":"If you face a problem and you want to revert previous version, please downgrade Karabiner-Elements as follows.\nUninstall Karabiner-Elements from uninstaller. Download a previous version from here. …","ref":"/docs/manual/operation/downgrade/","tags":"","title":"Downgrade"},{"body":" Karabiner-Elements is an open source software and you can use it without any purchases.\nSupporting this project This project accepts your funding via GitHub Sponsors or PayPal.\nFor donors I appreciate all donors. I received your donations!\nI’m afraid I don’t have enough time to reply for donors.\n(I’m giving priority to develop Karabiner-Elements at the moment.)\nDec 17, 2023\nTakayama Fumihiko Monthly or One-time (GitHub Sponsors) Takayama Fumihiko @tekezo Open GitHub Sponsors page One-time (PayPal) Open PayPal Payments Form (Pay $10 for Karabiner-Elements) Note: This is effectively a donation but it has taken the form of software fee because of Japanese law and the constraints on government regulation. Sponsors Thank you for supporting Karabiner-Elements! JavaScript is required to show sponsors. ","categories":"","description":"","excerpt":" Karabiner-Elements is an open source software and you can use it without any purchases.\nSupporting this project This project accepts your funding via GitHub Sponsors or PayPal.\nFor donors I …","ref":"/docs/pricing/","tags":"","title":"Pricing"},{"body":"If you manually registered Karabiner-Elements to Open at Login, the settings window will always appear at startup.\nKarabiner-Elements will start automatically via launchd even if it is not in Open at Login, so remove it from your Open at Login.\nOpen System Settings. Open General \u003e Login Items. Remove Karabiner-Elements from Open at Login. Caution Do not disable Karabiner-Elements.app in Allow in the Background. It’s a required setting for Karabiner-Elements to work. ","categories":"","description":"","excerpt":"If you manually registered Karabiner-Elements to Open at Login, the settings window will always appear at startup.\nKarabiner-Elements will start automatically via launchd even if it is not in Open at …","ref":"/docs/help/troubleshooting/preferences-window-shown-at-login/","tags":"","title":"Settings window is shown at login"},{"body":"to.halt is true or false. The default value is false.\nThe typical usage of to.halt is to cancel to_after_key_up if to_if_alone or to_if_held_down is triggered.\nPut \"halt\": true into to_if_alone or to_if_held_down if you want to suppress to_after_key_up when to_if_alone or to_if_held_down is triggered.\nExample The following json changes holding tab key to mission_control.\nThe halt in to_if_held_down suppresses to_after_key_up after mission_control is sent.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"tab\" }, \"to_after_key_up\": [ { \"key_code\": \"tab\" } ], \"to_if_held_down\": [ { \"key_code\": \"mission_control\", \"halt\": true } ] } ","categories":"","description":"","excerpt":"to.halt is true or false. The default value is false.\nThe typical usage of to.halt is to cancel to_after_key_up if to_if_alone or to_if_held_down is triggered.\nPut \"halt\": true into to_if_alone or …","ref":"/docs/json/complex-modifications-manipulator-definition/to/halt/","tags":"","title":"to.halt"},{"body":"This is the intended behavior.\nThe key code name using in Karabiner-Elements is HID usage name. This is close to the physical key location on the ANSI layout keyboard.\nFor this reason, there are mismatches of symbols actually input and key code names on non-ANSI keyboards.\nDetermining which characters are to be input by keyboard event is the later step in the processing flow of macOS. Karabiner-Elements changes input events on a layer closer to the hardware, which is why it works like this.\nPlease use key code names that matches your layout.\nANSI layout JIS layout Key code table Layout Symbols Key code name JIS @ open_bracket JIS [ close_bracket JIS ] backslash JIS \\ international3 JIS _ international1 Related articles Manual \u003e Configuration \u003e Set keyboard type ","categories":"","description":"","excerpt":"This is the intended behavior.\nThe key code name using in Karabiner-Elements is HID usage name. This is close to the physical key location on the ANSI layout keyboard.\nFor this reason, there are …","ref":"/docs/help/troubleshooting/symbols-with-non-ansi-keyboard/","tags":"","title":"Input symbols are different from the key code name on non-ANSI keyboards"},{"body":"to.hold_down_milliseconds is an integer value. The default value is 0.\nThe value is an interval of key_down and key_up when key_down and key_up events are sent at the same time such as multiple to events.\nNote Generally to.hold_down_milliseconds is used with \"key_code\": \"caps_lock\". Example The following json changes caps_lock key to sending caps_lock key_down, wait 200 milliseconds, caps_lock key_up.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"caps_lock\", \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"caps_lock\", \"hold_down_milliseconds\": 200 }, { \"key_code\": \"vk_none\" } ] } ","categories":"","description":"","excerpt":"to.hold_down_milliseconds is an integer value. The default value is 0.\nThe value is an interval of key_down and key_up when key_down and key_up events are sent at the same time such as multiple to …","ref":"/docs/json/complex-modifications-manipulator-definition/to/hold-down-milliseconds/","tags":"","title":"to.hold_down_milliseconds"},{"body":"This was discovered when using an MX Keys keyboard with the “Logi Options+” software. While Karabiner Elements is running, the Logitech specific function keys (such as Fn-esc to toggle between function keys and media keys and f1, f2, f3 to switch between inputs) are not recognized.\nThe solution is to edit karabiner.json such that the \"fn_function_keys\" array is empty:\n\"fn_function_keys\": [] Credit: https://github.com/pqrs-org/Karabiner-Elements/issues/1450#issuecomment-1013932206\n","categories":"","description":"","excerpt":"This was discovered when using an MX Keys keyboard with the “Logi Options+” software. While Karabiner Elements is running, the Logitech specific function keys (such as Fn-esc to toggle between …","ref":"/docs/help/troubleshooting/logitech-logi-options-plus-compatibility/","tags":"","title":"Compatibility with Logitech Logi Options+: Fn keys"},{"body":" Karabiner-Elements A powerful and stable keyboard customizer for macOS. Download v15.0.0 Toggle Dropdown Download v15.0.0 For macOS 15 Sequoia For macOS 14 Sonoma For macOS 13 Ventura Download v14.13.0 For macOS 12 Monterey For macOS 11 Big Sur Download v13.7.0 For macOS 10.15 Catalina (10.15.6 or later) Download v12.10.0 For macOS 10.15 Catalina For macOS 10.14 Mojave For macOS 10.13 High Sierra For macOS 10.12 Sierra Download v11.6.0 For macOS 10.11 El Capitan Download v10.22.0 For macOS 10.11 El Capitan For macOS 10.10 Yosemite For macOS 10.9 Mavericks Learn more Privacy Supported systems macOS 15 Sequoia\nmacOS 14 Sonoma\nmacOS 13 Ventura\nBoth Intel-based Macs and Apple Silicon Macs are supported. Predefined rules by community Release notes GitHub Sponsor Easy to use You can configure simple key mappings from GUI.\nRead more\nPowerful There are many powerful, predefined rules.\nDiamond cursor Emacs key bindings anywhere Vi key bindings Prevent unintended command-q Mouse keys You can import them from the Internet.\nRead more\nFlexible You can write your own rules if you want to modify existing rules or create new rules from scratch.\nRead more\nSponsors Thank you for supporting Karabiner-Elements! JavaScript is required to show sponsors. ","categories":"","description":"","excerpt":" Karabiner-Elements A powerful and stable keyboard customizer for macOS. Download v15.0.0 Toggle Dropdown Download v15.0.0 For macOS 15 Sequoia For macOS 14 Sonoma For macOS 13 Ventura Download …","ref":"/","tags":"","title":"Karabiner-Elements"}]
\ No newline at end of file
diff --git a/docs/offline-search-index.7807772b4f01f8e6f5e7a25b2274e3f7.json b/docs/offline-search-index.7807772b4f01f8e6f5e7a25b2274e3f7.json
deleted file mode 100644
index 3bc3fe6ee..000000000
--- a/docs/offline-search-index.7807772b4f01f8e6f5e7a25b2274e3f7.json
+++ /dev/null
@@ -1 +0,0 @@
-[{"body":"Under normal circumstances, there is no need to read this page, as the necessary settings have already been made during the initial setup.\nHowever, we describe the macOS settings that are made during the initial setup of Karabiner-Elements for the following cases.\nIf you canceled during the initial setup and want to continue in the middle of the process If you want to check the macOS settings made during the initial setup If Karabiner-Elements is not working properly and you want to make sure that macOS is configured properly Keep background items enabled Note This setting exists only on macOS Ventura or later Karabier-Elements has processes running constantly in the background, that handle input events. You have to keep the background items enabled in macOS System Settings \u003e General \u003e Login Items.\nEnable Input Monitoring Karabiner-Elements requires Input Monitoring permission to receive and modify input events.\nYou can enable it in macOS System Settings \u003e Privacy \u0026 Security \u003e Input Monitoring.\nTroubleshooting If you cannot find karabiner_grabber or karabiner_observer in the list, this is because you have not closed the following “Keystroke Receiving” dialogs.\nkarabiner_grabber and karabiner_observer will be shown in the list after the dialogs are closed.\nAllow system extension Karabiner-Elements uses the system extension to provide a virtual keyboard and mouse. You have to approve system extension before using it. You can confirm whether the system extension already allowed in EventViewer.\nIf org.pqrs.Karabiner-DriverKit-VirtualHIDDevice appears in the System Extensions of the EventViewer and the status is [activated enabled], the system extension is already allowed.\nOtherwise, you have to approve the system extension in macOS System Settings.\nApprove system extension You can approve the system extension in macOS System Settings \u003e Privacy \u0026 Security.\n","categories":"","description":"","excerpt":"Under normal circumstances, there is no need to read this page, as the necessary settings have already been made during the initial setup.\nHowever, we describe the macOS settings that are made during …","ref":"/docs/manual/misc/required-macos-settings/","tags":"","title":"Required macOS settings"},{"body":"Usually, the following driver alert will appear on first start-up and the alert will disappear after you allow the system software from System Settings.\nUnfortunately, the allow button may sometimes not appear in System Settings due to a problem with macOS driver loading.\nIn this case, you can display the allow button by deactivating and activating driver as described in the Advanced section on the alert.\nmacOS Catalina Notes Karabiner-Elements requires macOS 10.15.6 or later, because macOS 10.15.5 or earlier has an issue around DriverKit.\nPlease use Karabiner-Elements 12.10.0 if you are using macOS 10.15.5 or earlier.\nmacOS Catalina Note #1 Even worse, there is an additional problem on the macOS side if you are using macOS Catalina. The above steps might not resolve the issue and the alert may keep showing up.\nIf you are facing the problem, restart macOS between deactivating and activating to refresh the macOS internal state.\nPress Deactivate driver button. Enter the administrator password. Restart macOS. Press Activate driver button. Open Security \u0026 Privacy System Preferences and press the allow button. macOS Catalina Note #2 The problem is caused by macOS Catalina issues around DriverKit driver.\nKarabiner-Elements v12.10.0 uses a legacy kernel extension, so it is not affected by the macOS issues. So, downgrading to Karabiner-Elements 12.10.0 also solves the issue.\n","categories":"","description":"","excerpt":"Usually, the following driver alert will appear on first start-up and the alert will disappear after you allow the system software from System Settings.\nUnfortunately, the allow button may sometimes …","ref":"/docs/help/troubleshooting/driver-alert-keeps-showing-up/","tags":"","title":"Driver alert keeps showing up"},{"body":"The allow button in Privacy \u0026 Security System Settings appear for your approval after you open Karabiner-Elements for the first time.\nHowever, this allow button may not appear in some environments.\nReason The exact cause of the issue has not been determined, but it may be caused by the corrupted system cache by a macOS issue.\nThis issue may be resolved by starting macOS in safe mode to refresh the system cache.\nSteps Restart your Mac in safe mode by this instruction. Open Karabiner-Elements from Launchpad to ensure that Allow button is shown on System Settings. Open System Settings and confirm the Allow button is shown. If the Allow button is hidden, close System Settings and open it again. Click the Allow button. Restart your Mac and boot in normal mode. Note Karabiner-Elements does not work in safe mode. You have to restart macOS in normal mode to use Karabiner-Elements. ","categories":"","description":"","excerpt":"The allow button in Privacy \u0026 Security System Settings appear for your approval after you open Karabiner-Elements for the first time.\nHowever, this allow button may not appear in some environments. …","ref":"/docs/help/troubleshooting/allow-button-does-not-appear/","tags":"","title":"Allow button in Privacy \u0026 Security System Settings does not appear"},{"body":"“Device is ignored temporarily” alert will be shown in any of the following cases:\nIf you hold keys or buttons down before Karabiner-Elements open the device. Your device sends unintented key up events regardless you do not touch the keys.\n(e.g., Swiftpoint ProPoint sends key up events of the music play key periodically.) Press the described key or button again to dismiss the alert.\n","categories":"","description":"","excerpt":"“Device is ignored temporarily” alert will be shown in any of the following cases:\nIf you hold keys or buttons down before Karabiner-Elements open the device. Your device sends unintented key up …","ref":"/docs/manual/misc/ignored-temporarily/","tags":"","title":"About \"Device is ignored temporarily\" alert"},{"body":"The allow button in Privacy \u0026 Security System Settings should be hidden after you click it. If the button does not hide after click, you did not succeed to click it.\nReason The exact cause of the issue has not been determined, but it may be caused by the corrupted system cache by a macOS issue.\nThis issue may be resolved by starting macOS in safe mode to refresh the system cache.\nSteps Restart your Mac in safe mode by this instruction. Open Karabiner-Elements from Launchpad to ensure that Allow button is shown on System Settings. Open System Settings and confirm the Allow button is shown. If the Allow button is hidden, close System Settings and open it again. Click the Allow button. Restart your Mac and boot in normal mode. Note Karabiner-Elements does not work in safe mode. You have to restart macOS in normal mode to use Karabiner-Elements. ","categories":"","description":"","excerpt":"The allow button in Privacy \u0026 Security System Settings should be hidden after you click it. If the button does not hide after click, you did not succeed to click it.\nReason The exact cause of the …","ref":"/docs/help/troubleshooting/allow-button-does-not-work/","tags":"","title":"Allow button in Privacy \u0026 Security System Settings does not work"},{"body":"Send double click event by software. cg_event_double_click ensures that the click event occurs at the same location even if the mouse cursor is moving between the first click and the second click.\n{ \"to\": [ { \"software_function\": { \"cg_event_double_click\": { \"button\": 0 } } } ] } Name Required Description button Required An integer of CGMouseButton.\n0: Left Click\n1: Right Click\n2: Middle Click\n3,4,5,…,31: Other Buttons Low responsiveness This event will be lagged since it is sent by software implementation. It is better to send pointing_button::button1 twice instead of cg_event_double_click to get a better response. Accessibility cg_event_double_click uses the accessibility features. You have to allow karabiner_console_user_server in Privacy \u0026 Security System Settings.\nExamples Sending right button double click:\n{ \"to\": [ { \"software_function\": { \"cg_event_double_click\": { \"button\": 1 } } } ] } ","categories":"","description":"","excerpt":"Send double click event by software. cg_event_double_click ensures that the click event occurs at the same location even if the mouse cursor is moving between the first click and the second click.\n{ …","ref":"/docs/json/complex-modifications-manipulator-definition/to/software_function/cg_event_double_click/","tags":"","title":"cg_event_double_click"},{"body":"You can change a key to another key on Simple Modifications tab.\nChoose target device, then press Add item button. Select keys. (Tips: The following example changes the right option key to mouse button 3) Confirm the result using Karabiner-EventViewer. Tip You can find the key name by Karabiner-EventViewer.\n","categories":"","description":"","excerpt":"You can change a key to another key on Simple Modifications tab.\nChoose target device, then press Add item button. Select keys. (Tips: The following example changes the right option key to mouse …","ref":"/docs/manual/configuration/configure-simple-modifications/","tags":"","title":"Change a key to another key"},{"body":"Karabiner-Elements configuration file paths:\n~/.config/karabiner/karabiner.json Main configuration file.\nKarabiner-Elements watches this file and reload it automatically when it is updated. ~/.config/karabiner/assets/complex_modifications Imported complex_modifications files.\nYou can use them in Karabiner-Elements Settings \u003e Complex Modifications \u003e Add predefined rule. Tip: file update detection and automatic reload Karabiner-Elements watches ~/.config/karabiner/karabiner.json and reloads it if updated.\nThe mechanism is that Karabiner-Elements watches the parent directory ~/.config/karabiner by using the File System Events API.\nThus, Karabiner-Elements fails detecting file updates after you change the parent directory (e.g., recreate the parent directory).\nLog file Error messages will be output into ~/.local/share/karabiner/log/console_user_server.log if there are errors such as parse error.\nYou can also view the error messages in Karabiner-Elements Settings \u003e Log.\n","categories":"","description":"","excerpt":"Karabiner-Elements configuration file paths:\n~/.config/karabiner/karabiner.json Main configuration file.\nKarabiner-Elements watches this file and reload it automatically when it is updated. …","ref":"/docs/json/location/","tags":"","title":"File locations"},{"body":"{ \"from\": { \"key_code\": \"The name of key_code\", \"consumer_key_code\": \"The name of consumer_key_code\", \"pointing_button\": \"The name of pointing_button\", \"any\": \"key_code or consumer_key_code or pointing_button\", \"modifiers\": { \"mandatory\": [ modifier, modifier, ... ], \"optional\": [ modifier, modifier, ... ] }, \"simultaneous\": [ { \"key_code, consumer_key_code, pointing_button or any\" }, { \"key_code, consumer_key_code, pointing_button or any\" }, ... ], \"simultaneous_options\": { \"detect_key_down_uninterruptedly\": false, \"key_down_order\": \"A restriction of input events order\", \"key_up_order\": \"A restriction of input events order\", \"key_up_when\": \"When key_up events are posted\", \"to_after_key_up\": [ to event definition, to event definition, ... ] } } } Name Required Description key_code Optional Key code which you want to change consumer_key_code Optional Consumer key code (media key code) which you want to change pointing_button Optional Pointing button name which you want to change any Optional \"any\": \"key_code\", \"any\": \"consumer_key_code\" or \"any\": \"pointing_button\" modifiers Optional Specify mandatory and optional modifiers (e.g., “change control-h to delete”) simultaneous Optional Specify multiple events which are pressed simultaneously simultaneous_options Optional Options for simultaneous Note key_code, consumer_key_code, pointing_button and any are exclusive.\nYou have to specify one of them. Caution Be careful using \"pointing_button\": \"button1\" and \"any\": \"pointing_button\".\nYou may lose the left click button and system will be unusable. Detail from.any from.modifiers from.simultaneous from.simultaneous_options Investigate key names You can find key_code, consumer_key_code and pointing_button names by EventViewer. You can also confirm names in list. (See \"data\" in the list.) Tip You can also specify key_code, consumer_key_code, pointing_button with raw number as follows.\n{ \"from\": { \"key_code\": 41 } } Do not add double quotes when you use the raw number.\nTable of Contents ","categories":"","description":"","excerpt":"{ \"from\": { \"key_code\": \"The name of key_code\", \"consumer_key_code\": \"The name of consumer_key_code\", \"pointing_button\": \"The name of pointing_button\", \"any\": \"key_code or consumer_key_code or …","ref":"/docs/json/complex-modifications-manipulator-definition/from/","tags":"","title":"from event definition"},{"body":"You can use from.any as follows.\nThese matches all key codes, consumer key codes or pointing buttons.\n\"any\": \"key_code\" \"any\": \"consumer_key_code\" \"any\": \"pointing_button\" Caution Be careful using \"any\": \"pointing_button\".\nYou may lose the left click button and system will be unusable. ","categories":"","description":"","excerpt":"You can use from.any as follows.\nThese matches all key codes, consumer key codes or pointing buttons.\n\"any\": \"key_code\" \"any\": \"consumer_key_code\" \"any\": \"pointing_button\" Caution Be careful using …","ref":"/docs/json/complex-modifications-manipulator-definition/from/any/","tags":"","title":"from.any"},{"body":"Change an event if/unless the frontmost application is the specified application.\nExample Change control-h key to delete_or_backspace except in Terminal.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"h\", \"modifiers\": { \"mandatory\": [\"control\"], \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"delete_or_backspace\" } ], \"conditions\": [ { \"type\": \"frontmost_application_unless\", \"bundle_identifiers\": [\"^com\\\\.apple\\\\.Terminal$\"] } ] } Specification { \"type\": \"frontmost_application_if\", \"bundle_identifiers\": [ bundle identifier regex, bundle identifier regex, ... ], \"file_paths\": [ file path regex, file path regex, ... ] } Name Required Description type Required \"frontmost_application_if\" or \"frontmost_application_unless\" bundle_identifiers Optional Bundle identifier regexs such as [\"^com\\\\.apple\\\\.Terminal$\", \"^com\\\\.googlecode\\\\.iterm2$\"] file_paths Optional File path regexs such as [\"/Finder$\"] description Optional A human-readable comment Multiple bundle identifiers or file paths Multiple entries in bundle_identifiers and file_paths are joined by “or”.\nThe following condition is matched if bundle identifier is “com.apple.Terminal” or “com.googlecode.iterm2”.\n{ \"type\": \"frontmost_application_if\", \"bundle_identifiers\": [ \"^com\\\\.apple\\\\.Terminal$\", \"^com\\\\.googlecode\\\\.iterm2$\" ] } Investigate the bundle identifier and file path You can find the bundle identifier and file path by EventViewer \u003e Frontmost Application tab.\nOpen EventViewer, and then switch the frontmost application to an application which you want to know the bundle identifer or file path.\n","categories":"","description":"","excerpt":"Change an event if/unless the frontmost application is the specified application.\nExample Change control-h key to delete_or_backspace except in Terminal.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"h\", …","ref":"/docs/json/complex-modifications-manipulator-definition/conditions/frontmost-application/","tags":"","title":"frontmost_application_if, frontmost_application_unless"},{"body":"Karabiner-Elements does not modify mouse devices by default.\nYou have to enable your mouse on Karabiner-Elements Settings \u003e Devices. Then, use Simple Modifications to assign a key to a button or use Complex Modifications for more advanced usage. ","categories":"","description":"","excerpt":"Karabiner-Elements does not modify mouse devices by default.\nYou have to enable your mouse on Karabiner-Elements Settings \u003e Devices. Then, use Simple Modifications to assign a key to a button or use …","ref":"/docs/help/how-to/mouse-button/","tags":"","title":"How to change mouse buttons"},{"body":"Some operations are required to grant proper permission from macOS to Karabiner-Elements. Follow these instructions to set up Karabiner-Elements.\nInstall Karabiner-Elements Open the downloaded file. Open the .pkg file. The installer will be opened. Install Karabiner-Elements. Keep Login Items enabled Since macOS 13 Ventura, background item notifications will be shown after the installation.\nThe following Login Items in System Settings are required, and have to keep enabled.\nKarabiner-DriverKit-VirtualHIDDeviceClient.app Karabiner-Elements.app Note If you are using macOS 12 or prior, these items are not shown in System Preferences. Please proceed to the next step. Open Karabiner-Elements Settings Open Karabiner-Elements from Launchpad. Allow system software which provides virtual devices for Karabiner-Elements The following alert will be shown when you open Karabiner-Elements Settings. Click Open System Settings button, then press the Allow button. Note Please follow this instruction if there is any problem with the Allow button. Grant Input Monitoring to Karabiner-Elements processes Two Keystroke Receiving alerts will be shown on macOS Catalina or later after you allow the system software. Press the Open System Settings button on both alerts. System Settings will be opened after you press the Open System Settings button. Choose Privacy \u0026 Security \u003e Input Monitoring, and then enable karabiner_grabber and karabiner_observer. Setup your keyboard layout Keyboard Setup Assistant will be opened. Choose your keyboard layout. (ANSI, ISO or JIS) Configure Karabiner-Elements Enjoy keyboard configuration!\nConfiguration manual ","categories":"","description":"","excerpt":"Some operations are required to grant proper permission from macOS to Karabiner-Elements. Follow these instructions to set up Karabiner-Elements.\nInstall Karabiner-Elements Open the downloaded file. …","ref":"/docs/getting-started/installation/","tags":"","title":"Installation"},{"body":"Karabiner-Elements installs files into the following locations.\nSystem files /Applications/Karabiner-Elements.app /Applications/Karabiner-EventViewer.app /Library/Application Support/org.pqrs/Karabiner-Elements /Library/Application Support/org.pqrs/Karabiner-VirtualHIDDevice /Library/Application Support/org.pqrs/config /Library/Application Support/org.pqrs/tmp /Library/LaunchDaemons/org.pqrs.karabiner.karabiner_grabber.plist /Library/LaunchDaemons/org.pqrs.karabiner.karabiner_kextd.plist /Library/LaunchDaemons/org.pqrs.karabiner.karabiner_observer.plist /Library/LaunchAgents/org.pqrs.karabiner.agent.karabiner_grabber.plist /Library/LaunchAgents/org.pqrs.karabiner.agent.karabiner_observer.plist /Library/LaunchAgents/org.pqrs.karabiner.karabiner_console_user_server.plist /Library/LaunchAgents/org.pqrs.karabiner.karabiner_session_monitor.plist /var/log/karabiner User files ~/.config/karabiner ~/.local/share/karabiner ~/Library/Preferences/org.pqrs.Karabiner-Elements.Preferences.plist ~/Library/Preferences/org.pqrs.Karabiner-Elements.Settings.plist ~/Library/Preferences/org.pqrs.Karabiner-Elements.Updater.plist ~/Library/Preferences/org.pqrs.Karabiner-EventViewer.plist ~/Library/Preferences/org.pqrs.Karabiner-Menu.plist ~/Library/Preferences/org.pqrs.Karabiner-MultitouchExtension.plist Warning If you want to remove Karabiner-Elements, you have to use uninstaller. ","categories":"","description":"","excerpt":"Karabiner-Elements installs files into the following locations.\nSystem files /Applications/Karabiner-Elements.app /Applications/Karabiner-EventViewer.app /Library/Application …","ref":"/docs/help/advanced-topics/installed-files/","tags":"","title":"Installed files"},{"body":"mouse_motion_to_scroll changes mouse cursor movement to scroll wheel.\n{ \"type\": \"mouse_motion_to_scroll\", \"from\": { \"modifiers\": { \"mandatory\": [...], \"optional\": [...] } }, \"conditions\": ..., \"options\": { \"momentum_scroll_enabled\": true, \"speed_multiplier\": 1.0 } } Key Value Required Description type \"mouse_motion_to_scroll\" Required — from.modifiers Same as basic.from.modifiers Optional Enable mouse_motion_to_scroll if specified modifiers are pressed conditions Same as basic.conditions Optional Enable mouse_motion_to_scroll when specified conditions options An object of parameters Optional — Caution You should set either from.modifiers or conditions.\nYour mouse cursor movement will be always changed to scroll and your mouse will be unusable without from.modifiers and conditions.\nOptions Key Value Required Description momentum_scroll_enabled true or false Optional Enable Momentum scroll. The default value is true. speed_multiplier float value Optional Multiply scroll speed. The default value is 1.0. Example The following json changes button4 + mouse movement to scroll.\n[ { \"type\": \"basic\", \"from\": { \"pointing_button\": \"button4\", \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"set_variable\": { \"name\": \"enable_mouse_motion_to_scroll\", \"value\": 1 } } ], \"to_after_key_up\": [ { \"set_variable\": { \"name\": \"enable_mouse_motion_to_scroll\", \"value\": 0 } } ] }, { \"type\": \"mouse_motion_to_scroll\", \"from\": { \"modifiers\": { \"optional\": [\"any\"] } }, \"conditions\": [ { \"type\": \"variable_if\", \"name\": \"enable_mouse_motion_to_scroll\", \"value\": 1 } ] } ] ","categories":"","description":"","excerpt":"mouse_motion_to_scroll changes mouse cursor movement to scroll wheel.\n{ \"type\": \"mouse_motion_to_scroll\", \"from\": { \"modifiers\": { \"mandatory\": [...], \"optional\": [...] } }, \"conditions\": ..., …","ref":"/docs/json/complex-modifications-manipulator-definition/other-types/mouse-motion-to-scroll/","tags":"","title":"mouse_motion_to_scroll"},{"body":"Karabiner-MultitouchExtension allows you to change keys only when the finger is on the trackpad.\nYou can use variable_if or variable_unless to determine either the finger is on trackpad.\nExample The following json changes k key to up_arrow when the finger is on the trackpad.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"k\", \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"up_arrow\" } ], \"conditions\": [ { \"type\": \"variable_unless\", \"name\": \"multitouch_extension_finger_count_total\", \"value\": 0 } ] } Variables Karabiner-MultitouchExtension changes the following variables when the finger count on the trackpad is changed.\nName Value multitouch_extension_finger_count_total Total count of fingers on the trackpad multitouch_extension_finger_count_upper_half_area Count of fingers on the upper half of trackpad multitouch_extension_finger_count_lower_half_area Count of fingers on the lower half of trackpad multitouch_extension_finger_count_left_half_area Count of fingers on the left half of trackpad multitouch_extension_finger_count_right_half_area Count of fingers on the right half of trackpad Note finger_count_total == finger_count_upper_half_area + finger_count_lower_half_area finger_count_total == finger_count_left_half_area + finger_count_right_half_area You can confirm the variables state on Karabiner-EventViewer \u003e Variables.\n","categories":"","description":"","excerpt":"Karabiner-MultitouchExtension allows you to change keys only when the finger is on the trackpad.\nYou can use variable_if or variable_unless to determine either the finger is on trackpad.\nExample The …","ref":"/docs/json/extra/multitouch-extension/","tags":"","title":"MultitouchExtension integration"},{"body":"Karabiner-Elements keeps running in the background even if you close the settings window.\nTo quit Karabiner-Elements, choose “Quit Karabiner-Elements” from menu bar.\nNote If you’ve hidden the menu bar icon, you can also quit Karabiner-Elements from Settings.\n","categories":"","description":"","excerpt":"Karabiner-Elements keeps running in the background even if you close the settings window.\nTo quit Karabiner-Elements, choose “Quit Karabiner-Elements” from menu bar.\nNote If you’ve hidden the menu bar …","ref":"/docs/manual/operation/quit/","tags":"","title":"Quit"},{"body":"shell_command executes the shell command.\nExamples Open application { \"to\": [ { \"shell_command\": \"open -a 'Safari.app'\" } ] } Execute shell from file { \"to\": [ { \"shell_command\": \"/bin/sh ~/opt/shell_commands/hello.sh\" } ] } Advanced topic The very limited environment variables are passed to the command, $HOME, $UID, $USER, etc.\nExport environment variables in shell_command if your commands depend them.\nFor example, the following command does not work well with unicode characters because tr command depends the current locale.\n{ \"to\": [ { \"shell_command\": \"pbpaste | tr '[:upper:]' '[:lower:]' | pbcopy\" } ] } You have to set LC_ALL in shell_command in this case.\n{ \"to\": [ { \"shell_command\": \"export LC_ALL=en_US.UTF-8; pbpaste | tr '[:upper:]' '[:lower:]' | pbcopy\" } ] } ","categories":"","description":"","excerpt":"shell_command executes the shell command.\nExamples Open application { \"to\": [ { \"shell_command\": \"open -a 'Safari.app'\" } ] } Execute shell from file { \"to\": [ { \"shell_command\": \"/bin/sh …","ref":"/docs/json/complex-modifications-manipulator-definition/to/shell-command/","tags":"","title":"to.shell_command"},{"body":"In Allow in the Background of Login Items, Fumihiko Takayama may appear instead of Karabiner-Elements.\nThere are several causes, but the problem is mainly on the macOS side and is difficult to resolve. (Restarting macOS may solve this issue)\nIn any case, there is no problem with leaving it as it is.\nExpected:\nInformation for those who want to know more The confirmed causes are as follows:\nIf you have ever git clone the Karabiner-Elements repository and built it If macOS has set the Allow in the Background display name before Karabiner-Elements was registered in the macOS application database How to solve when you have built Karabiner-Elements from source code The Login Items referes Launch Services database to determine the display name.\nIf you have built Karabiner-Elements from source code, your built binaries in the working directory are registered Launch Services automatically.\nWe assume Login Items mixes the information of binaries in your working directory and installed from the package, and failed to get the correct information. Therefore, in Login Items, the signing developer’s name is displayed instead.\nSo purging unintended entries in Launch Services database solves this issue.\nSteps Run the following command in Terminal to get the list of registered applications.\n/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -gc -dump | grep ^path | grep Karabiner-Elements The result example:\npath: /Users/tekezo/.Trash/Karabiner-Elements.app (0x6a38) path: /Users/tekezo/Library/Developer/Xcode/DerivedData/Karabiner-Elements-aljilynxkbdxwddtylopomxdislp/Build/Products/Debug/Karabiner-Elements.app (0x6bf8) path: /Library/Application Support/org.pqrs/Karabiner-Elements/Karabiner-Menu.app (0x7918) path: /Library/Application Support/org.pqrs/Karabiner-Elements/Karabiner-NotificationWindow.app (0x7930) path: /Library/Application Support/org.pqrs/Karabiner-Elements/Karabiner-Elements.app/Contents/Frameworks/Sparkle.framework/Versions/B/Updater.app (0x7938) path: /Library/Application Support/org.pqrs/Karabiner-Elements/Karabiner-Elements.app (0x793c) path: /Applications/Karabiner-Elements.app (0x7940) path: /Library/Application Support/org.pqrs/Karabiner-Elements/Karabiner-MultitouchExtension.app (0x7944) path: /Users/tekezo/Library/Developer/Xcode/DerivedData/Karabiner-Elements-enyghegdpximkigqjnasmtnnkupb/Build/Products/Release/Karabiner-Elements.app (0x54c4) Next, unregister the path to the built binaries, those containing Xcode, build, etc, from the list.\n/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -u '/Users/tekezo/.Trash/Karabiner-Elements.app' /System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -u '/Users/tekezo/Library/Developer/Xcode/DerivedData/Karabiner-Elements-aljilynxkbdxwddtylopomxdislp/Build/Products/Debug/Karabiner-Elements.app' ... Finally, restart macOS.\n","categories":"","description":"","excerpt":"In Allow in the Background of Login Items, Fumihiko Takayama may appear instead of Karabiner-Elements.\nThere are several causes, but the problem is mainly on the macOS side and is difficult to …","ref":"/docs/help/troubleshooting/fumihiko-takayama-in-login-items/","tags":"","title":"\"Fumihiko Takayama\" is shown in Login Items"},{"body":"You can restart Karabiner-Elements from Settings.\n","categories":"","description":"","excerpt":"You can restart Karabiner-Elements from Settings.\n","ref":"/docs/manual/operation/restart/","tags":"","title":"Restart"},{"body":"You can enable the sticky modifier keys from Karabiner-Elements Settings \u003e Simple modifications.\nNote The sticky modifier keys acts as general modifier key while you are pressing and holding down the key.\nFor example, the following operation result is AA instead of Aa.\nPress sticky left shift key Press a key Release a key Press a key Release a key Release sticky left shift key If you want to disable this feature, use sticky modifier key (pressing and holding down is disabled).\nSticky modifier key indicator Sticky modifier key indicator will be shown while the sticky modifiers are active.\nYou can hide the indicator from Karabiner-Elements Settings \u003e UI.\nSticky modifiers and mouse events The sticky modifiers are not deactivate by mouse buttons if you are not enabled the mouse.\nThere are two solutions:\nDeactivate sticky modifier by press the sticky modifier key again. Enable your mouse on Devices. ","categories":"","description":"","excerpt":"You can enable the sticky modifier keys from Karabiner-Elements Settings \u003e Simple modifications.\nNote The sticky modifier keys acts as general modifier key while you are pressing and holding down the …","ref":"/docs/help/how-to/sticky-modifier-key/","tags":"","title":"How to use sticky modifier keys"},{"body":"Change an event if/unless the event is from specified device.\nExample Change 1 key to f1 if the device is Apple keyboard.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"1\", \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"f1\" } ], \"conditions\": [ { \"type\": \"device_if\", \"identifiers\": [ { \"vendor_id\": 1452 }, { \"vendor_id\": 76 } ] } ] } Specification { \"type\": \"device_if\", \"identifiers\": [ { \"vendor_id\": 1111, \"product_id\": 2222, \"description\": \"my keyboard 1\" }, { \"vendor_id\": 3333, \"product_id\": 4444, \"description\": \"my keyboard 2\" }, ... ] } Name Required Description type Required \"device_if\" or \"device_unless\" or \"device_exists_if\" or \"device_exists_unless\" identifiers Required Target device definitions description Optional A human-readable comment type Type Description Available since device_if Valid only for devices specified in identifiers Karabiner-Elements 11.0.0 device_unless Valid only for devices other than specified in identifiers Karabiner-Elements 11.0.0 device_exists_if Valid if a specified device is connected Karabiner-Elements 14.8.4 device_exists_unless Valid unless a specified device is connected Karabiner-Elements 14.8.4 identifiers identifiers is an array of objects.\nName Required Description Fixed Value vendor_id Optional Vendor ID of device Yes product_id Optional Product ID of device Yes device_address Optional Bluetooth address (Bluetooth MAC address) of device (only available for Bluetooth devices) (available since Karabiner-Elements 14.12.2) Yes [1] location_id Optional Location ID of device No [2] is_keyboard Optional true or false Yes is_pointing_device Optional true or false Yes is_game_pad Optional true or false\n(available since Karabiner-Elements 14.12.4) Yes is_touch_bar Optional true or false Yes is_built_in_keyboard Optional true or false\n(available since Karabiner-Elements 14.8.2) Yes [1] The device_address will change when you replace the hardware. [2] The location_id will change when you change the USB port which the device is connected. Multiple identifiers If you specify multiple identifiers (vendor_id, product_id, location_id, …), these are joined by “and”.\nThe following condition is matched if Vendor ID is 1111 and Product ID is 2222.\n{ \"type\": \"device_if\", \"identifiers\": [ { \"vendor_id\": 1111, \"product_id\": 2222 } ] } Multiple entries If you specify multiple entries at identifiers, conditions are joined by “or”.\nThe following condition is matched if Vendor ID is 1111 or 1112.\n{ \"type\": \"device_if\", \"identifiers\": [ { \"vendor_id\": 1111 }, { \"vendor_id\": 1112 } ] } Investigate the device identifiers You can find them by EventViewer \u003e Devices tab.\n","categories":"","description":"","excerpt":"Change an event if/unless the event is from specified device.\nExample Change 1 key to f1 if the device is Apple keyboard.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"1\", \"modifiers\": { \"optional\": …","ref":"/docs/json/complex-modifications-manipulator-definition/conditions/device/","tags":"","title":"device_if, device_unless, device_exists_if, device_exists_unless"},{"body":"Karabiner-Elements is a powerful and stable keyboard customizer for macOS.\nCore features Simple Modifications: Change normal keys to other keys. Complex Modifications: Change keys by complex rules. Change a key to combination of modifiers. (e.g. change capslock to control+command) Change modifiers+key to key. (e.g. change control+m to return) Send key events if a key is pressed alone. Send key events if keys are pressed simultaneously. Mouse keys. etc. Function Keys: Change f1-f12 keys to media controls. Devices: Apply modifications to specified keyboards only. Profiles: Support multiple profiles. 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. Extra Key Support: Enable extra keys on PC keyboard that are not recognized by default in macOS. Home key on iPad keyboards such as Logitech K480 International keys Language keys (e.g., 無変換,変換, カタカナ keys on JIS PC keyboard) Application Launch Keys 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 Settings \u003e Keyboard \u003e Keyboard Shortcuts... \u003e Modifier Keys configuration. Change modifiers by using Simple Modifications. (Detail of input event modification chaining) ","categories":"","description":"","excerpt":"Karabiner-Elements is a powerful and stable keyboard customizer for macOS.\nCore features Simple Modifications: Change normal keys to other keys. Complex Modifications: Change keys by complex rules. …","ref":"/docs/getting-started/features/","tags":"","title":"Features"},{"body":"from.modifiers is a object which has the following keys.\nKey Value Required Description mandatory An array of strings Optional Modifiers which must be pressed optional An array of strings Optional Modifiers which can be pressed from.modifiers.mandatory Events are manipulated only if mandatory modifiers are pressed. Mandatory modifiers are removed from to events. from.modifiers.optional Events are also manipulated even if optional modifiers are pressed. Optional modifiers are kept in to events. Tip If you do not include any in modifiers.optional, your manipulator does not change event if extra modifiers (modifiers which are not included in modifiers.mandatory) are pressed. List of modifiers modifiers.mandatory and modifiers.optional are array of the folowing strings.\nName Description caps_lock — left_command — left_control — left_option — left_shift — right_command — right_control — right_option — right_shift — fn — command Either left command or right command is pressed control Either left control or right control is pressed option Either left option or right option is pressed shift Either left shift or right shift is pressed left_alt Alias of left_option (available since Karabiner-Elements 12.3.0) left_gui Alias of left_command (available since Karabiner-Elements 12.3.0) right_alt Alias of right_option (available since Karabiner-Elements 12.3.0) right_gui Alias of right_command (available since Karabiner-Elements 12.3.0) any Any modifiers Examples Without modifiers This json defines manipulator which changes escape to tab.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"escape\" }, \"to\": [ { \"key_code\": \"tab\" } ] } Without modifiers, the event is changed only any modifiers are not pressed. Input Output Manipulated escape tab Manipulated left_shift + escape left_shift + escape Not manipulated left_control + escape left_control + escape Not manipulated With modifiers.optional This json defines manipulator which changes escape to tab. (left_shift and left_control can be pressed.)\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"escape\", \"modifiers\": { \"optional\": [\"left_shift\", \"left_control\"] } }, \"to\": [ { \"key_code\": \"tab\" } ] } The optional modifiers (left_shift and left_control) are kept in output events. The event is not changed if modifiers are not included in optional such as left_option. Input Output Manipulated escape tab Manipulated left_shift + escape left_shift + tab Manipulated left_control + escape left_control + tab Manipulated left_option + escape left_option + escape Not manipulated left_shift + left_option + escape left_shift + left_option + escape Not manipulated With modifiers.mandatory This json defines manipulator which changes control + h to delete_or_backspace.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"h\", \"modifiers\": { \"mandatory\": [\"control\"] } }, \"to\": [ { \"key_code\": \"delete_or_backspace\" } ] } The mandatory modifier (control) are removed in output events. The event is not changed if left_control and right_control are not pressed. Input Output Manipulated h h Not manipulated left_control + h delete_or_backspace Manipulated left_control + left_option + h left_control + left_option + h Not manipulated With modifiers.mandatory and modifiers.optional { \"type\": \"basic\", \"from\": { \"key_code\": \"h\", \"modifiers\": { \"mandatory\": [\"control\"], \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"delete_or_backspace\" } ] } The mandatory modifier (control) are removed in output events. The event is not changed if left_control and right_control are not pressed. \"optional\": [\"any\"] allows any modifiers. Input Output Manipulated h h Not manipulated left_control + h delete_or_backspace Manipulated left_control + left_option + h left_option + delete_or_backspace Manipulated left_control + left_shift + h left_shift + delete_or_backspace Manipulated ","categories":"","description":"","excerpt":"from.modifiers is a object which has the following keys.\nKey Value Required Description mandatory An array of strings Optional Modifiers which must be pressed optional An array of strings Optional …","ref":"/docs/json/complex-modifications-manipulator-definition/from/modifiers/","tags":"","title":"from.modifiers"},{"body":"Karabiner-Elements disables the caps lock delay without any action since v13.3.0.\n","categories":"","description":"","excerpt":"Karabiner-Elements disables the caps lock delay without any action since v13.3.0.\n","ref":"/docs/help/how-to/disable-caps-lock-delay/","tags":"","title":"How to disable caps lock delay"},{"body":"Karabiner-Elements modifies following behavior automatically without any configurations:\nShare state of modifier keys with all connected keyboards When you are using multiple keyboards, modifier keys are shared with all keyboards.\nFor example, pressing “shift key on keyboard1” and “space key on keyboard2” sends shift-space.\nAdd fn-key combinations Karabiner adds fn-key combinations:\nfn-arrow keys Key combination Result fn-up arrow page up fn-down arrow page down fn-left arrow home fn-right arrow end others Key combination Result fn-return enter fn-delete forward delete ","categories":"","description":"","excerpt":"Karabiner-Elements modifies following behavior automatically without any configurations:\nShare state of modifier keys with all connected keyboards When you are using multiple keyboards, modifier keys …","ref":"/docs/manual/misc/implicit-behavior/","tags":"","title":"Implicit behavior"},{"body":"It’s an issue of macOS that macOS update sometimes does not restore the running process state sufficiently after macOS update.\nPlease follow the instruction to solve the problem.\nRestart macOS once again after macOS update. Reinstall Karabiner-Elements if restart macOS does not solve the problem. ","categories":"","description":"","excerpt":"It’s an issue of macOS that macOS update sometimes does not restore the running process state sufficiently after macOS update.\nPlease follow the instruction to solve the problem.\nRestart macOS once …","ref":"/docs/help/troubleshooting/stopped-working-after-macos-update/","tags":"","title":"Karabiner-Elements stopped working after macOS update"},{"body":"Security is one of the most important point of Karabiner-Elements architecture design.\nSeparating process and running them with properly privileges to prevent event leaks.\nProcess Karabiner-Elements restricts the input event handling to karabiner_observer and karabiner_grabber processes.\nThese process are running with root privilege and other process including malicious attacker cannot steal your input events.\nList of process Running with root privilege\nkarabiner_observer Role: Observe the keyboard hardware events and tell grabber the devices state. karabiner_grabber Role: Grab the keyboard hardware and catch events, modify events then post them. Karabiner VirtualHIDDevice kernel extension Role: Virtual keyboard and pointing device. The virtual devices deny any requires (sending input events) from non root privileged processes.\nTypically, karabiner_grabber is the only process which can send input events to the virtual devices. Running with logged in user privilege\nkarabiner_console_user_server Role: Tell karabiner_grabber starting device grabbing. Execute shell commands which is triggered by karabiner_grabber. karabiner_session_monitor Role: Monitor user login status and tell it to karabiner_grabber. karabiner_observer (Running with logged in user) Role: Tell macOS karabiner_observer will be use Input Monitoring.\nAnd do nothing if the process is running with non root user. karabiner_grabber (Running with logged in user) Role: Tell macOS karabiner_grabber will be use Input Monitoring.\nAnd do nothing if the process is running with non root user. ","categories":"","description":"","excerpt":"Security is one of the most important point of Karabiner-Elements architecture design.\nSeparating process and running them with properly privileges to prevent event leaks.\nProcess Karabiner-Elements …","ref":"/docs/help/advanced-topics/security/","tags":"","title":"Security"},{"body":"Move the mouse cursor to the specified point.\n{ \"to\": [ { \"software_function\": { \"set_mouse_cursor_position\": { \"x\": 0, \"y\": 0, \"screen\": 0 } } } ] } Name Required Description x Required The new mouse cursor position y Required The new mouse cursor position screen Optional The screen index of the new mouse cursor origin Position format There are two styles to specify the position.\nType Format Example Point integer { \"x\": 100 } Percent “xx%” { \"x\": \"50%\" } Examples Set the mouse cursor position to (0,0) of the second screen.\n{ \"to\": [ { \"software_function\": { \"set_mouse_cursor_position\": { \"x\": 0, \"y\": 0, \"screen\": 1 } } } ] } Set the mouse cursor position to center of the first screen.\n{ \"to\": [ { \"software_function\": { \"set_mouse_cursor_position\": { \"x\": \"50%\", \"y\": \"50%\", \"screen\": 0 } } } ] } ","categories":"","description":"","excerpt":"Move the mouse cursor to the specified point.\n{ \"to\": [ { \"software_function\": { \"set_mouse_cursor_position\": { \"x\": 0, \"y\": 0, \"screen\": 0 } } } ] } Name Required Description x Required The new mouse …","ref":"/docs/json/complex-modifications-manipulator-definition/to/software_function/set_mouse_cursor_position/","tags":"","title":"set_mouse_cursor_position"},{"body":"{ \"key_code\": \"The name of key_code\", \"consumer_key_code\": \"The name of consumer_key_code\", \"pointing_button\": \"The name of pointing_button\", \"shell_command\": \"shell command\", \"select_input_source\": { \"language\": \"language regex\", \"input_source_id\": \"input source id regex\", \"input_mode_id\": \"input mode id regex\" }, \"set_variable\": { \"name\": \"variable name\", \"value\": \"variable value\" }, \"mouse_key\": mouse_key definition, \"sticky_modifier\": sticky modifier definition, \"software_function\": software function definition, \"modifiers\": [ modifier, modifier, ... ], \"lazy\": false, \"repeat\": true, \"halt\": false, \"hold_down_milliseconds\": 0 } Note The following keys are exclusive. You cannot specify multiple items into one to entry.\nkey_code consumer_key_code pointing_button shell_command select_input_source set_variable mouse_key sticky_modifier software_function (software_function is available since Karabiner-Elements v13.5.1) Name Required Description key_code Optional Key code which you want to post consumer_key_code Optional Consumer key code (media key code) which you want to post pointing_button Optional Pointing button name which you want to post shell_command Optional Shell command which you want to execute select_input_source Optional Input source which you want to switch set_variable Optional A varaible name and value which you want to change mouse_key Optional A mouse key definition sticky_modifier Optional A sticky modifier key definition software_function Optional A software function definition modifiers Optional Modifiers which are post with the event lazy Optional Lazy modifier flag repeat Optional Key repeat flag halt Optional A flag for to_after_key_up hold_down_milliseconds Optional Interval of key_down and key_up when these events are sent at the same time Investigate key names You can find key_code, consumer_key_code and pointing_button names by EventViewer. You can also confirm names in list. (See \"data\" in the list.) Tip You can also specify key_code, consumer_key_code, pointing_button with raw number as follows.\n{ \"to\": [ { \"key_code\": 41 } ] } Table of Contents ","categories":"","description":"","excerpt":"{ \"key_code\": \"The name of key_code\", \"consumer_key_code\": \"The name of consumer_key_code\", \"pointing_button\": \"The name of pointing_button\", \"shell_command\": \"shell command\", \"select_input_source\": { …","ref":"/docs/json/complex-modifications-manipulator-definition/to/","tags":"","title":"to event definition"},{"body":"select_input_source change the current input source.\nCaution Switching to input sources which have input_mode_id (Chinese, Japanese, Korean, Vietnamese) may be failed due to an macOS issue.\nFor CJKV input sources, sending the input source switch shortcut (e.g., control-space) is better than using select_input_source.\n{ \"to\": [ { \"select_input_source\": { \"language\": \"language regex\", \"input_source_id\": \"input source id regex\", \"input_mode_id\": \"input mode id regex\" } } ] } Name Required Description language Optional The language regex such as \"^en$\", \"^fr$\" input_source_id Optional The input source id regex such as \"^com\\\\.apple\\\\.keylayout\\\\.US$\" input_mode_id Optional The input mode id regex such as \"^com\\\\.apple\\\\.inputmethod\\\\.Japanese\\\\.Hiragana$\" Example Switch to French input source.\n{ \"to\": [ { \"select_input_source\": { \"language\": \"^fr$\" } } ] } Investigate the input source identifiers You can find the current input source identifiers by EventViewer \u003e Variables tab.\n{ \"input_source\": { \"input_mode_id\": \"com.apple.inputmethod.Japanese\", \"input_source_id\": \"com.google.inputmethod.Japanese.base\", \"language\": \"ja\" } } ","categories":"","description":"","excerpt":"select_input_source change the current input source.\nCaution Switching to input sources which have input_mode_id (Chinese, Japanese, Korean, Vietnamese) may be failed due to an macOS issue.\nFor CJKV …","ref":"/docs/json/complex-modifications-manipulator-definition/to/select-input-source/","tags":"","title":"to.select_input_source"},{"body":"Swap ; and : (Equal to swap ; and shift-;)\n[ { \"type\": \"basic\", \"from\": { \"key_code\": \"semicolon\", \"modifiers\": { \"mandatory\": [\"shift\"], \"optional\": [\"caps_lock\"] } }, \"to\": [ { \"key_code\": \"semicolon\" } ] }, { \"type\": \"basic\", \"from\": { \"key_code\": \"semicolon\", \"modifiers\": { \"optional\": [\"caps_lock\"] } }, \"to\": [ { \"key_code\": \"semicolon\", \"modifiers\": [\"left_shift\"] } ] } ] Change control-h to delete And change control-option-h to option-delete.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"h\", \"modifiers\": { \"mandatory\": [\"control\"], \"optional\": [\"caps_lock\", \"option\"] } }, \"to\": [ { \"key_code\": \"delete_or_backspace\" } ] } Disable command-l on Finder { \"type\": \"basic\", \"from\": { \"key_code\": \"l\", \"modifiers\": { \"mandatory\": [\"command\"], \"optional\": [\"caps_lock\"] } }, \"conditions\": [ { \"type\": \"frontmost_application_if\", \"bundle_identifiers\": [\"^com\\\\.apple\\\\.finder$\"] } ] } Post escape if left_control is pressed alone { \"type\": \"basic\", \"from\": { \"key_code\": \"left_control\", \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"left_control\", \"lazy\": true } ], \"to_if_alone\": [ { \"key_code\": \"escape\" } ] } Open Alfred 4 if escape is held down { \"type\": \"basic\", \"from\": { \"key_code\": \"escape\", \"modifiers\": { \"optional\": [\"caps_lock\"] } }, \"parameters\": { \"basic.to_if_alone_timeout_milliseconds\": 250, \"basic.to_if_held_down_threshold_milliseconds\": 250 }, \"to_if_alone\": [ { \"key_code\": \"escape\" } ], \"to_if_held_down\": [ { \"shell_command\": \"open -a 'Alfred 4.app'\" } ] } Change right_shift x2 to mission_control [ { \"type\": \"basic\", \"from\": { \"key_code\": \"right_shift\", \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"mission_control\" } ], \"conditions\": [ { \"type\": \"variable_if\", \"name\": \"right_shift pressed\", \"value\": 1 } ] }, { \"type\": \"basic\", \"from\": { \"key_code\": \"right_shift\", \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"set_variable\": { \"name\": \"right_shift pressed\", \"value\": 1 } }, { \"key_code\": \"right_shift\" } ], \"to_delayed_action\": { \"to_if_invoked\": [ { \"set_variable\": { \"name\": \"right_shift pressed\", \"value\": 0 } } ], \"to_if_canceled\": [ { \"set_variable\": { \"name\": \"right_shift pressed\", \"value\": 0 } } ] } } ] Change equal+delete to forward_delete if these keys are pressed simultaneously { \"type\": \"basic\", \"from\": { \"simultaneous\": [ { \"key_code\": \"equal_sign\" }, { \"key_code\": \"delete_or_backspace\" } ], \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"delete_forward\" } ] } ","categories":"","description":"","excerpt":"Swap ; and : (Equal to swap ; and shift-;)\n[ { \"type\": \"basic\", \"from\": { \"key_code\": \"semicolon\", \"modifiers\": { \"mandatory\": [\"shift\"], \"optional\": [\"caps_lock\"] } }, \"to\": [ { \"key_code\": …","ref":"/docs/json/typical-complex-modifications-examples/","tags":"","title":"Typical complex_modifications examples"},{"body":"Karabiner-Elements provides built-in uninstaller.\nUse the uninstaller to remove Karabiner-Elements from your system.\nYou can launch the uninstaller from “Launch uninstaller” button on Uninstall tab. Then, follow the instruction of the dialog. (The uninstaller ask your administrator password in order to remove files.)\nUninstall from command line If you don’t want to use above GUI, you can also uninstall Karabiner-Elements from command line.\nbash '/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/scripts/uninstall/deactivate_driver.sh' sudo '/Library/Application Support/org.pqrs/Karabiner-Elements/uninstall.sh' (Administrator password is required to run the above command.)\nAdditional uninstallation Some settings and files will remain after uninstallation. It does not affect the system even if it remains in place, but if you are concerned about them, please delete them manually.\nInput Monitoring settings Remove karabiner_grabber and karabiner_observer from the Input Monitoring settings in macOS Settings. Log files Delete the following directories: /var/log/karabiner ~/.local/share/karabiner Temporary directories Delete the following directories: /Library/Application Support/org.pqrs/tmp Setting files Delete the following directories: ~/.config/karabiner Advanced topic Operation not permitted error will occur if you try removing files by rm command.\nsudo rm -rf /Applications/Karabiner-Elements.app rm: /Applications/Karabiner-Elements.app/Contents: Operation not permitted rm: /Applications/Karabiner-Elements.app: Operation not permitted Karabiner-Elements forces you to use uninstaller to remove files in order to ensure remove files outside /Applications.\nSee Installed files to confirm the files.\nManual uninstallation If you want to remove files without uninstaller, unlock app files from command line with this instruction.\nAnd then, remove installed files by hand, and reboot your Mac.\n","categories":"","description":"","excerpt":"Karabiner-Elements provides built-in uninstaller.\nUse the uninstaller to remove Karabiner-Elements from your system.\nYou can launch the uninstaller from “Launch uninstaller” button on Uninstall tab. …","ref":"/docs/manual/operation/uninstall/","tags":"","title":"Uninstall"},{"body":"Karabiner-Elements provides more complex event modifications.\nThese rules change keys by conditions.\nExamples 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. There are two ways to add rules\nImport predefined rules maintained by the community Create your own rules In both cases, you can modify the rules later to make them more personalised.\nImport predefined rules Step 1 Open Complex Modifications tab and press Add predefined rule button, then press Import more rules from the internet button.\nOfficial rules site will be open using your default web browser.\nStep 2 Press Import button in the page.\nA confirmation dialog is shown. Press Allow button.\nStep 3 Karabiner-Elements is shown again. Press Import button, then new rules are imported.\nStep 4 Press Enable button.\nStep 5 New rule is enabled.\nConfirm the result using Karabiner-EventViewer.\nCreate your own rules Step 1 Open Complex Modifications tab and press Add your own rule button.\nStep 2 An editor will open with sample rules. Change the content and press the Save button to register.\nWhen making changes, Karabiner-EventViewer and Karabiner Configuration Reference Manual can be used to confirm the key names and how to write rules.\nEdit rules Open Complex Modifications tab and press Edit button. The editor will open. Change the contents and save it.\nWhen making changes, Karabiner-EventViewer and Karabiner Configuration Reference Manual can be used to confirm the key names and how to write rules.\n","categories":"","description":"","excerpt":"Karabiner-Elements provides more complex event modifications.\nThese rules change keys by conditions.\nExamples Modifier flags + key to keys: Change control-m to return key. Change control-h to delete …","ref":"/docs/manual/configuration/configure-complex-modifications/","tags":"","title":"Use more complex rules"},{"body":"Karabiner-Elements does not provide virtual modifiers, however you can make your own flag similar to virtual modifier using variables.\nExample The following json change keypad_1 to virtual modifier.\nChange keypad_1 to virtual modifier (my_modifier_1). Change keypad_1 + a to mission_control. Change keypad_1 + s to launchpad. [ { \"type\": \"basic\", \"from\": { \"key_code\": \"keypad_1\", \"modifiers\": { \"mandatory\": [], \"optional\": [\"any\"] } }, \"to\": [ { \"set_variable\": { \"name\": \"my_modifier_1\", \"value\": 1 } } ], \"to_after_key_up\": [ { \"set_variable\": { \"name\": \"my_modifier_1\", \"value\": 0 } } ] }, { \"type\": \"basic\", \"from\": { \"key_code\": \"a\", \"modifiers\": { \"mandatory\": [], \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"mission_control\" } ], \"conditions\": [ { \"type\": \"variable_if\", \"name\": \"my_modifier_1\", \"value\": 1 } ] }, { \"type\": \"basic\", \"from\": { \"key_code\": \"s\", \"modifiers\": { \"mandatory\": [], \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"launchpad\" } ], \"conditions\": [ { \"type\": \"variable_if\", \"name\": \"my_modifier_1\", \"value\": 1 } ] } ] ","categories":"","description":"","excerpt":"Karabiner-Elements does not provide virtual modifiers, however you can make your own flag similar to virtual modifier using variables.\nExample The following json change keypad_1 to virtual modifier. …","ref":"/docs/json/extra/virtual-modifier/","tags":"","title":"Virtual modifier"},{"body":"You can check for updates from Update tab.\nTip If you want to use the latest beta version, use “Check for beta updates” button.\n","categories":"","description":"","excerpt":"You can check for updates from Update tab.\nTip If you want to use the latest beta version, use “Check for beta updates” button.\n","ref":"/docs/manual/operation/check-for-updates/","tags":"","title":"Check for updates"},{"body":"Choose devices which Karabiner-Elements modifies events on Devices tab.\nTip Mice are disabled by default.\nYou have to enable them if you want to change the mouse buttons in Karabiner-Elements. ","categories":"","description":"","excerpt":"Choose devices which Karabiner-Elements modifies events on Devices tab.\nTip Mice are disabled by default.\nYou have to enable them if you want to change the mouse buttons in Karabiner-Elements. ","ref":"/docs/manual/configuration/configure-devices/","tags":"","title":"Choose devices"},{"body":"The manipulators are evaluated from the top to the bottom and the input event is manipulated only the first matched manipulator.\nIn other words, if there are multiple manipulators which change the same key, the manipulator placed at the top is applied and other manipulators are ignored.\nSimple Modifications and Complex Modifications Simple Modifications and Complex Modifications are independent.\nThus, Simple Modifications does not affect above priority.\nKarabiner-Elements changes keys by Simple Modifications, and then changes them by Complex Modifications.\nAbout input event modification chaining.\nExample If there are the following manipulators, right shift key will be right command + right option.\nSimple Modifications Change right shift to right command Complex Modifications Change right command to right command + right option ","categories":"","description":"","excerpt":"The manipulators are evaluated from the top to the bottom and the input event is manipulated only the first matched manipulator.\nIn other words, if there are multiple manipulators which change the …","ref":"/docs/json/complex-modifications-manipulator-evaluation-priority/","tags":"","title":"complex_modifications manipulator evaluation priority"},{"body":"simultaneous manipulates keys which are pressed simultaneously in 50 milliseconds.\nExample This json defines manipulator which changes a+s+d to mission_control.\n{ \"type\": \"basic\", \"from\": { \"simultaneous\": [ { \"key_code\": \"a\" }, { \"key_code\": \"s\" }, { \"key_code\": \"d\" } ], \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"mission_control\" } ] } Note There are some cases simultaneous does not modify events.\nsimultaneous does not modify events if any from events are released before all from events are pressed. simultaneous does not modify events if from events are interrupted by another key_down event. Manipulated input #1 Input: a key_down s key_down d key_down Output: mission_control Manipulated input #2 Input: s key_down a key_down d key_down Output: mission_control Not manipulated input #1 a is released before all input events are pressed.\nInput: a key_down s key_down a key_up d key_down Output: a key_down s key_down a key_up d key_down Not manipulated input #2 Another key (f) is pressed before all input events are pressed.\nInput: a key_down s key_down f key_down d key_down Output: a key_down s key_down f key_down d key_down About key_up The key_up event is posted when you release any from events.\nFor example, changing tab+q to mission_control works as follows.\nInput Output tab key_down — q key_down mission_control key_down tab key_up mission_control key_up q key_up — Change threshold milliseconds You can adjust threshold on Karabiner-Elements Settings \u003e Parameters.\nIt is same as adjusting basic.simultaneous_threshold_milliseconds parameter in json.\n","categories":"","description":"","excerpt":"simultaneous manipulates keys which are pressed simultaneously in 50 milliseconds.\nExample This json defines manipulator which changes a+s+d to mission_control.\n{ \"type\": \"basic\", \"from\": { …","ref":"/docs/json/complex-modifications-manipulator-definition/from/simultaneous/","tags":"","title":"from.simultaneous"},{"body":"Karabiner-Elements treats input events by the following order:\nCatch events from hardware. Apply Simple Modifications. Apply Complex Modifications. Apply Function Keys Modifications. (change f1…f12 keys to media controls) Post events to applications via a virtual keyboard. Note System modifier keys configuration in System Settings \u003e Keyboard \u003e Keyboard Shortcuts… \u003e Modifier Keys is ignored when you use Karabiner-Elements.\nChange modifier keys in Karabiner-Elements’s Simple Modifications.\n","categories":"","description":"","excerpt":"Karabiner-Elements treats input events by the following order:\nCatch events from hardware. Apply Simple Modifications. Apply Complex Modifications. Apply Function Keys Modifications. (change f1…f12 …","ref":"/docs/manual/misc/event-modification-chaining/","tags":"","title":"Input event modification chaining"},{"body":"Causes an immediate system sleep.\nAvailable since iokit_power_management_sleep_system is available since Karabiner-Elements 13.7.1. { \"to\": [ { \"software_function\": { \"iokit_power_management_sleep_system\": { \"delay_milliseconds\": 500 } } } ] } Name Required Description delay_milliseconds Optional Waiting time before the system goes to sleep Examples Use default delay_milliseconds (500 ms).\n{ \"to\": [ { \"software_function\": { \"iokit_power_management_sleep_system\": {} } } ] } ","categories":"","description":"","excerpt":"Causes an immediate system sleep.\nAvailable since iokit_power_management_sleep_system is available since Karabiner-Elements 13.7.1. { \"to\": [ { \"software_function\": { …","ref":"/docs/json/complex-modifications-manipulator-definition/to/software_function/iokit_power_management_sleep_system/","tags":"","title":"iokit_power_management_sleep_system"},{"body":"Karabiner-Elements does not provide a feature to adjust key repeat rate.\nUse System Settings \u003e Keyboard.\nYou can also adjust the key repeat rate using defaults write command. https://apple.stackexchange.com/questions/10467/how-to-increase-keyboard-key-repeat-rate-on-os-x\n","categories":"","description":"","excerpt":"Karabiner-Elements does not provide a feature to adjust key repeat rate.\nUse System Settings \u003e Keyboard.\nYou can also adjust the key repeat rate using defaults write command. …","ref":"/docs/help/how-to/key-repeat/","tags":"","title":"Is it possible to adjust the key repeat rate?"},{"body":"Change an event if/unless the event is from specified type keyboard.\nExample Change control-[ key to escape, including JIS layout support. (the [ key is close_bracket in JIS layout)\n[ { \"type\": \"basic\", \"from\": { \"key_code\": \"open_bracket\", \"modifiers\": { \"mandatory\": [\"control\"], \"optional\": [\"caps_lock\"] } }, \"to\": [ { \"key_code\": \"escape\" } ], \"conditions\": [ { \"keyboard_types\": [\"ansi\", \"iso\"], \"type\": \"keyboard_type_if\" } ] }, { \"type\": \"basic\", \"from\": { \"key_code\": \"close_bracket\", \"modifiers\": { \"mandatory\": [\"control\"], \"optional\": [\"caps_lock\"] } }, \"to\": [ { \"key_code\": \"escape\" } ], \"conditions\": [ { \"keyboard_types\": [\"jis\"], \"type\": \"keyboard_type_if\" } ] } ] Specification { \"type\": \"keyboard_type_if\", \"keyboard_types\": [\"ansi\", \"iso\"] } Name Required Description type Required \"keyboard_type_if\" or \"keyboard_type_unless\" keyboard_types Required An array of \"ansi\", \"iso\" or \"jis\" description Optional A human-readable comment Multiple keyboard types keyboard_types are joined by “or”.\nThe following condition is matched if the keyboard type is “ansi” or “iso”.\n{ \"type\": \"keyboard_type_if\", \"keyboard_types\": [\"ansi\", \"iso\"] } ","categories":"","description":"","excerpt":"Change an event if/unless the event is from specified type keyboard.\nExample Change control-[ key to escape, including JIS layout support. (the [ key is close_bracket in JIS layout)\n[ { \"type\": …","ref":"/docs/json/complex-modifications-manipulator-definition/conditions/keyboard-type/","tags":"","title":"keyboard_type_if, keyboard_type_unless"},{"body":"to_if_alone posts events when the from key is pressed alone.\nThe events are posted at the from key is released.\nExample The following json changes left_control to sending escape when left_control is pressed alone.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"left_control\", \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"left_control\", \"lazy\": true } ], \"to_if_alone\": [ { \"key_code\": \"escape\" } ] } About cancellation to_if_alone is canceled if other events (keys, buttons or scroll wheel) is happen while the from key is pressed down.\nThe cancellation also happens when you press the from key long. (The default timeout is 1000 milliseconds.)\nYou can adjust the timeout milliseconds by parameters \u003e basic.to_if_alone_timeout_milliseconds.\nThe following example sets the timeout 500 milliseconds.\n{ \"from\": ..., \"to\": ..., \"to_if_alone\": [ { \"key_code\": \"escape\" } ], \"parameters\": { \"basic.to_if_alone_timeout_milliseconds\": 500 }, \"type\": \"basic\" } About keyboard repeat to_if_alone posts both key_down and key_up events at the same time.\nThus, you cannot use key repeat for to_if_alone events.\n","categories":"","description":"","excerpt":"to_if_alone posts events when the from key is pressed alone.\nThe events are posted at the from key is released.\nExample The following json changes left_control to sending escape when left_control is …","ref":"/docs/json/complex-modifications-manipulator-definition/to-if-alone/","tags":"","title":"to_if_alone"},{"body":"set_variable defines and updates the variable value.\nTip set_variable is designed to use with variable_if and variable_unless conditions. { \"to\": [ { \"set_variable\": { \"name\": \"variable name\", \"value\": variable value, \"key_up_value\": variable value, \"type\": \"set\" } } ] } Name Required Description Available since name Required Target variable name. Karabiner-Elements 11.0.0 value Required | Optional Target variable value. Karabiner-Elements 11.0.0 key_up_value Optional A variable value when key is up Karabiner-Elements 14.12.6 type Optional “set” or “unset” Karabiner-Elements 14.99.2 Note: If key_up_value or type is specified, the value can be omitted.\nAvailable types of value Type Example value Available since integer 0,1,2,… Karabiner-Elements 11.0.0 boolean true, false Karabiner-Elements 14.4.20 string “layer1”, “layer2” Karabiner-Elements 14.4.20 Examples { \"set_variable\": { \"name\": \"mode_flag\", \"value\": 1, \"key_up_value\": 0 } } { \"set_variable\": { \"name\": \"mode_enabled\", \"value\": true } } { \"set_variable\": { \"name\": \"layer_name\", \"value\": \"layer1\" } } { \"set_variable\": { \"name\": \"my_flag\", \"type\": \"unset\" } } Confirm the current variable values You can see the current variable values by EventViewer \u003e Variables.\n","categories":"","description":"","excerpt":"set_variable defines and updates the variable value.\nTip set_variable is designed to use with variable_if and variable_unless conditions. { \"to\": [ { \"set_variable\": { \"name\": \"variable name\", …","ref":"/docs/json/complex-modifications-manipulator-definition/to/set-variable/","tags":"","title":"to.set_variable"},{"body":"It’s an issue of macOS, and unfortunately, Karabiner-Elements cannot avoid this issue.\nInstead, please change fn+number keys to function keys in Karabiner-Elements configuration.\nImport Map fn + number keys to function keys Enable Map fn + number keys to their corresponding function keys. You can use f1-f12 keys by fn+number keys. Note If you are using “Use all F1, F2, etc. keys as standard function keys.”, enable Map fn + number keys to their corresponding media control keys instead. Detail of the problem The fn key events are ignored by Touch Bar since the following facts.\nTouch Bar accepts the fn key event only from the build-in keyboard. The fn key events are sent from Karabiner’s virtual keyboard when Karabiner-Elements is running. Unfortunately, posting input events via own virtual keyboard is the only way to accomplish the stable input event modification.\nIn other words, we cannot post the fn key event through the built-in keyboard if we want to change key events stably.\n","categories":"","description":"","excerpt":"It’s an issue of macOS, and unfortunately, Karabiner-Elements cannot avoid this issue.\nInstead, please change fn+number keys to function keys in Karabiner-Elements configuration.\nImport Map fn + …","ref":"/docs/help/troubleshooting/touch-bar-function-keys/","tags":"","title":"Touch Bar does not change to f1-f12 when I press the fn key"},{"body":" Info This content is for older versions of Karabiner Elements. Prior to Karabiner-Elements 14.10.0, a lock indicator is shown on Karabiner-Elements and Karabiner-EventViewer icon.\nThese indicators show that these files are protected so that they cannot be deleted from Finder.\nWhy these files are protected This protection is intended to prevent incomplete uninstallation.\nKarabiner-Elements is a system-wide software, and files are installed in appropriate locations besides the Applications folder.\nTherefore, if you just put the application icon in Trash like a normal app uninstallation, some files will be left behind.\nThe file protection forces to use the built-in uninstaller and remove installed files properly at the uninstallation.\nAdvanced topic This file locking is achieved with schg and uchg flags.\nYou can unlock these files by running the following commands in Terminal. (Administrator password is required to run the commands.)\nsudo chflags nouchg,noschg /Applications/Karabiner-Elements.app sudo chflags nouchg,noschg /Applications/Karabiner-EventViewer.app In particular, if Full Disk Access rights have not been granted to Terminal, “Operation not permitted” error may be displayed. In this case, the safest solution is to grant App Management rights to Terminal.\n","categories":"","description":"","excerpt":" Info This content is for older versions of Karabiner Elements. Prior to Karabiner-Elements 14.10.0, a lock indicator is shown on Karabiner-Elements and Karabiner-EventViewer icon.\nThese indicators …","ref":"/docs/help/advanced-topics/lock-icon/","tags":"","title":"What is the lock indicator on Karabiner-Elements and Karabiner-EventViewer icon"},{"body":"set_notification_message sets or remove the notification message.\n{ \"to\": [ { \"set_notification_message\": { \"id\": \"identifier of the message\", \"text\": \"message text\" } } ] } Name Required Description id Required Specify an unique string for your notification message text Required Message body How to remove the notification message Set empty string to text to remove the notification message. Examples Show the notification message while you press right shift key.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"right_shift\", \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { // Show the notification message \"set_notification_message\": { \"id\": \"org.pqrs.notificaion_message_example\", \"text\": \"Hello World!\" } }, { \"key_code\": \"right_shift\" } ], \"to_after_key_up\": [ { // Hide the notification message \"set_notification_message\": { \"id\": \"org.pqrs.notificaion_message_example\", \"text\": \"\" } } ] } Important Do not forget to remove the notification message. ","categories":"","description":"","excerpt":"set_notification_message sets or remove the notification message.\n{ \"to\": [ { \"set_notification_message\": { \"id\": \"identifier of the message\", \"text\": \"message text\" } } ] } Name Required Description …","ref":"/docs/json/complex-modifications-manipulator-definition/to/set-notification-message/","tags":"","title":"to.set_notification_message"},{"body":"Karabiner-Elements provides a built-in event viewer named Karabiner-EventViewer. You can show keyboard and mouse events by using it.\nOpen Karabiner-EventViewer from Launchpad. Input events will be shown when you type keyboard on EventViewer or press pointing buttons on Mouse Area. ","categories":"","description":"","excerpt":"Karabiner-Elements provides a built-in event viewer named Karabiner-EventViewer. You can show keyboard and mouse events by using it.\nOpen Karabiner-EventViewer from Launchpad. Input events will be …","ref":"/docs/manual/operation/eventviewer/","tags":"","title":"Confirm the result of configuration (EventViewer)"},{"body":"It’s an issue of macOS, and unfortunately, Karabiner-Elements cannot avoid this issue.\nInstead, please change fn+escape to eject and use control+fn+escape (== control+eject) shortcut.\nImport Change escape key. Enable Change fn+escape to eject.\nYou can use control+fn+escape as control+eject. ","categories":"","description":"","excerpt":"It’s an issue of macOS, and unfortunately, Karabiner-Elements cannot avoid this issue.\nInstead, please change fn+escape to eject and use control+fn+escape (== control+eject) shortcut.\nImport Change …","ref":"/docs/help/troubleshooting/control-eject/","tags":"","title":"Control-eject shortcut does not work when Karabiner-Elements is running"},{"body":"You can disable MacBook built-in keyboard if external keyboards are connected.\nThis feature is useful when you put the external keybaord on top of the built-in keyboard.\nEnable Disable the built-in keyboard while this device is connected in Devices tab.\nConfigure the built-in keyboard detection Enable Treat as a built-in keyboard in Devices if your built-in keyboard is not recognized properly or you want to add a device that will be disabled,\n","categories":"","description":"","excerpt":"You can disable MacBook built-in keyboard if external keyboards are connected.\nThis feature is useful when you put the external keybaord on top of the built-in keyboard.\nEnable Disable the built-in …","ref":"/docs/manual/configuration/disable-built-in-keyboard/","tags":"","title":"Disable the built-in keyboard when external keyboard is connected"},{"body":"simultaneous_options adjust the simultaneous behavior.\nKey Value Description detect_key_down_uninterruptedly true or false Specify whether key_down detection is interrupted with unrelated events key_down_order insensitive, strict or strict_inverse Restriction of key_down order key_up_order insensitive, strict or strict_inverse Restriction of key_up order key_up_when any or all When key_up events are posted to_after_key_up An array of to event definitions Events will be posted when all from events are released detect_key_down_uninterruptedly If detect_key_down_uninterruptedly is true, Karabiner-Elements changes simultaneous events even if unrelated key down event exists between target events.\nFor example, when escape+3 -\u003e mission_control, escape,1,3 will be mission_control,1 if detect_key_down_uninterruptedly is true.\nThe default value is false.\nkey_down_order simultaneous checks the order of key_down events if key_down_order is specified and is not insensitive.\nFor example, this definition manipulates tab,q to mission_control and does not manipulate q,tab events.\n{ \"type\": \"basic\", \"from\": { \"simultaneous\": [ { \"key_code\": \"tab\" }, { \"key_code\": \"q\" } ], \"simultaneous_options\": { \"key_down_order\": \"strict\" }, \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"mission_control\" } ] } key_up_order simultaneous checks the order of key_up events if key_up_order is specified and is not insensitive.\nTip key_up_order is ignored if simultaneous_threshold_milliseconds is reached.\nYou should set a large value to simultaneous_threshold_milliseconds when you use key_up_order.\nFor example, this definition manipulates tab,q to mission_control if the tab key is released before the q key within 500 milliseconds.\nInput Output tab \u0026 q key_down — tab key_up mission_control key_down, mission_control key_up q key_up — Note Events will be posted just before the last from event’s key_up. { \"type\": \"basic\", \"parameters\": { \"basic.simultaneous_threshold_milliseconds\": 500 }, \"from\": { \"simultaneous\": [ { \"key_code\": \"tab\" }, { \"key_code\": \"q\" } ], \"simultaneous_options\": { \"key_up_order\": \"strict\" }, \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"mission_control\" } ] } key_up_when Specify when key_up events are posted.\nValue Description any Post key_up events when any key is released all Post key_up events when all keys are released to_after_key_up to_after_key_up will be posted when all from events are released.\nThis feature is typically used to clear mode flag variables when all from events are released.\nExample:\nMouse Keys Mode v4 json json generator Import ","categories":"","description":"","excerpt":"simultaneous_options adjust the simultaneous behavior.\nKey Value Description detect_key_down_uninterruptedly true or false Specify whether key_down detection is interrupted with unrelated events …","ref":"/docs/json/complex-modifications-manipulator-definition/from/simultaneous-options/","tags":"","title":"from.simultaneous_options"},{"body":"Karabiner-Elements will be started automatically at login after once you have run Karabiner-ELements.\nQuit Karabiner-Elements if you want to stop running Karabiner-Elements at login.\n","categories":"","description":"","excerpt":"Karabiner-Elements will be started automatically at login after once you have run Karabiner-ELements.\nQuit Karabiner-Elements if you want to stop running Karabiner-Elements at login.\n","ref":"/docs/help/how-to/disable-open-at-login/","tags":"","title":"How to disable running Karabiner-Elements at login"},{"body":"Change an event if/unless the current input source is the specified value.\nExample Switching input source between Japanese and English at tapping the left command key.\n[ { \"type\": \"basic\", \"from\": { \"key_code\": \"left_command\", \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"left_command\", \"lazy\": true } ], \"to_if_alone\": [ { \"key_code\": \"japanese_eisuu\" } ], \"to_if_held_down\": [ { \"key_code\": \"left_command\" } ], \"conditions\": [ { \"input_sources\": [ { \"language\": \"ja\" } ], \"type\": \"input_source_if\" } ], \"parameters\": { \"basic.to_if_held_down_threshold_milliseconds\": 100 } }, { \"type\": \"basic\", \"from\": { \"key_code\": \"left_command\", \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"left_command\", \"lazy\": true } ], \"to_if_alone\": [ { \"key_code\": \"japanese_kana\" } ], \"to_if_held_down\": [ { \"key_code\": \"left_command\" } ], \"conditions\": [ { \"input_sources\": [ { \"language\": \"en\" } ], \"type\": \"input_source_if\" } ], \"parameters\": { \"basic.to_if_held_down_threshold_milliseconds\": 100 } } ] Specification { \"type\": \"input_source_if\", \"input_sources\": [ { \"language\": \"language regex\", \"input_source_id\": \"input source id regex\", \"input_mode_id\": \"input mode id regex\" }, { \"language\": \"language regex\", \"input_source_id\": \"input source id regex\", \"input_mode_id\": \"input mode id regex\" }, ... ] } Name Required Description type Required \"input_source_if\" or \"input_source_unless\" input_sources Required Target input source definitions description Optional A human-readable comment input_sources input_sources is an array of objects.\nName Required Description language Optional The language regex such as \"^en$\", \"^ja$\" input_source_id Optional The input source id regex such as \"^com\\\\.apple\\\\.keylayout\\\\.US$\" input_mode_id Optional The input mode id regex such as \"^com\\\\.apple\\\\.inputmethod\\\\.Japanese\\\\.Hiragana$\" Multiple identifiers If you specify multiple identifiers (language, input_source_id or input_mode_id), these are joined by “and”.\nThe following condition is matched if language is “ja” and input_mode_id is “com.apple.inputmethod.Japanese.Hiragana”.\n{ \"type\": \"input_source_if\", \"input_sources\": [ { \"language\": \"^ja$\", \"input_mode_id\": \"^com\\\\.apple\\\\.inputmethod\\\\.Japanese\\\\.Hiragana$\" } ] } Multiple entries If you specify multiple entries at input_sources, conditions are joined by “or”.\nThe following condition is matched if language is “en” or “ja”.\n{ \"type\": \"input_source_if\", \"input_sources\": [ { \"language\": \"^en$\" }, { \"language\": \"^ja$\" } ] } Investigate the input source identifiers You can find the current input source identifiers by EventViewer \u003e Variables tab.\n{ \"input_source\": { \"input_mode_id\": \"com.apple.inputmethod.Japanese\", \"input_source_id\": \"com.google.inputmethod.Japanese.base\", \"language\": \"ja\" } } ","categories":"","description":"","excerpt":"Change an event if/unless the current input source is the specified value.\nExample Switching input source between Japanese and English at tapping the left command key.\n[ { \"type\": \"basic\", \"from\": { …","ref":"/docs/json/complex-modifications-manipulator-definition/conditions/input-source/","tags":"","title":"input_source_if, input_source_unless"},{"body":" Note Karabiner-Elements does not allow you including comments (// ... or /* ... */) in any json files. karabiner.json { \"global\": { \"check_for_updates_on_startup\": true, \"show_in_menu_bar\": true, \"show_profile_name_in_menu_bar\": false }, \"profiles\": [ { \"name\": \"Profile name\", \"selected\": true, \"simple_modifications\": [ ... ], \"fn_function_keys\": [ ... ], \"complex_modifications\": { \"parameters\": { ... }, \"rules\": [ ... ] }, \"virtual_hid_keyboard\": { \"keyboard_type\": \"ansi\", \"caps_lock_delay_milliseconds\": 0 }, \"devices\": [ ... ], \"parameters\": { ... } }, { \"name\": \"Profile name\", \"selected\": false, ... }, ... ] } complex_modifications in karabiner.json \u003e profiles { \"complex_modifications\": { \"parameters\": { ... }, \"rules\": [ { \"description\": \"This description is shown in Settings.\", \"manipulators\": [ { \"type\": \"basic\", \"from\": from event definition, \"to\": [ to event definition, to event definition, ... ], \"to_if_alone\": [ to event definition, to event definition, ... ], \"to_if_held_down\": [ to event definition, to event definition, ... ], \"to_after_key_up\": [ to event definition, to event definition, ... ], \"to_delayed_action\": { \"to_if_invoked\": [ to event definition, to event definition, ... ], \"to_if_canceled\": [ to event definition, to event definition, ... ] }, \"conditions\": [ condition definition, condition definition, ... ], \"parameters\": { ... }, \"description\": \"Optional description for human\" }, { \"type\": \"basic\", ... }, ... ] }, { \"description\": \"...\", \"manipulators\": [ ... ] }, ... ] } } custom *.json file in ~/config/karabiner/assets/complex_modifications Note Adding a custom .json file allows for enabling and disabling rules/complex modifications through the UI. { \"title\": \"Title for the list of rules/complex modifications.\", \"rules\": [ { \"description\": \"This description is shown in Settings.\", \"manipulators\": [ { \"type\": \"basic\", \"from\": from event definition, \"to\": [ to event definition, to event definition, ... ], \"to_if_alone\": [ to event definition, to event definition, ... ], \"to_if_held_down\": [ to event definition, to event definition, ... ], \"to_after_key_up\": [ to event definition, to event definition, ... ], \"to_delayed_action\": { \"to_if_invoked\": [ to event definition, to event definition, ... ], \"to_if_canceled\": [ to event definition, to event definition, ... ] }, \"conditions\": [ condition definition, condition definition, ... ], \"parameters\": { ... }, \"description\": \"Optional description for human\" }, { \"type\": \"basic\", ... }, ... ] }, { \"description\": \"...\", \"manipulators\": [ ... ] }, ... ] } ","categories":"","description":"","excerpt":" Note Karabiner-Elements does not allow you including comments (// ... or /* ... */) in any json files. karabiner.json { \"global\": { \"check_for_updates_on_startup\": true, \"show_in_menu_bar\": true, …","ref":"/docs/json/root-data-structure/","tags":"","title":"karabiner.json data structure"},{"body":"Karabiner-MultitouchExtension allows you to change keys only when your finger is on the trackpad.\nNote Karabiner-MultitouchExtension is available since Karabiner-Elements 12.6.9 Related Complex Modifications examples Multitouch Vi Mode Multitouch Diamond Cursor Multitouch Mouse Buttons ThumbSense MultitouchExtension usage Open MultitouchExtension app from Karabiner-Elements Settings \u003e Misc. Enable “Start at login” on MultitouchExtension Preferences. Adjust the effective area of the trackpad. Tip If you hid Karabiner-MultitouchExtension icon in Dock, press “Open MultitouchExtension app” button on Preferences \u003e Misc to open Karabiner-MultitouchExtension Preferences. How to integrate MultitouchExtension to your complex modifications See karabiner.json reference manual\n","categories":"","description":"","excerpt":"Karabiner-MultitouchExtension allows you to change keys only when your finger is on the trackpad.\nNote Karabiner-MultitouchExtension is available since Karabiner-Elements 12.6.9 Related Complex …","ref":"/docs/manual/misc/multitouch-extension/","tags":"","title":"MultitouchExtension"},{"body":"to_if_held_down posts events when the from key is held down.\nNote If to events are specified, key_up event of to is sent before to_if_held_down events are posted. Example The following json changes the escape key to open Alfred when the escape key is held down.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"escape\", \"modifiers\": { \"optional\": [\"caps_lock\"] } }, \"parameters\": { \"basic.to_if_alone_timeout_milliseconds\": 250, \"basic.to_if_held_down_threshold_milliseconds\": 250 }, \"to_if_alone\": [ { \"key_code\": \"escape\" } ], \"to_if_held_down\": [ { \"shell_command\": \"open -a 'Alfred 4.app'\" } ] } Parameter You can adjust the threshold of holding down periods by parameters \u003e basic.to_if_held_down_threshold_milliseconds like the above example.\n","categories":"","description":"","excerpt":"to_if_held_down posts events when the from key is held down.\nNote If to events are specified, key_up event of to is sent before to_if_held_down events are posted. Example The following json changes …","ref":"/docs/json/complex-modifications-manipulator-definition/to-if-held-down/","tags":"","title":"to_if_held_down"},{"body":"Move mouse pointer and scroll by mouse_key.\n{ \"to\": [ { \"mouse_key\": { \"x\": speed, \"y\": speed, \"vertical_wheel\": speed, \"horizontal_wheel\": speed, \"speed_multiplier\": 1.0 } } ] } Name Required Description x Optional Move left (x \u003c 0) or right (x \u003e 0) y Optional Move up (y \u003c 0) or down (y \u003e 0) vertical_wheel Optional Scroll up (vertical_wheel \u003c 0) or down (vertical_wheel \u003e 0) horizontal_wheel Optional Scroll left (horizontal_wheel \u003e 0) or right (horizontal_wheel \u003c 0) speed_multiplier Optional Multiply mouse keys speed while this key is hold down Note Speed and scroll direction depend on System Settings \u003e Mouse configuration. Examples json Move left { \"mouse_key\": { \"x\": -1536 } } Move right { \"mouse_key\": { \"x\": 1536 } } Move up { \"mouse_key\": { \"y\": -1536 } } Move down { \"mouse_key\": { \"y\": 1536 } } Scroll left { \"mouse_key\": { \"horizontal_wheel\": 32 } } Scroll right { \"mouse_key\": { \"horizontal_wheel\": -32 } } Scroll up { \"mouse_key\": { \"vertical_wheel\": -32 } } Scroll down { \"mouse_key\": { \"vertical_wheel\": 32 } } Complete json examples Mouse keys (simple) Mouse Keys Mode v4 ","categories":"","description":"","excerpt":"Move mouse pointer and scroll by mouse_key.\n{ \"to\": [ { \"mouse_key\": { \"x\": speed, \"y\": speed, \"vertical_wheel\": speed, \"horizontal_wheel\": speed, \"speed_multiplier\": 1.0 } } ] } Name Required …","ref":"/docs/json/complex-modifications-manipulator-definition/to/mouse-key/","tags":"","title":"to.mouse_key"},{"body":"It’s a hardware limitation of your keyboard called “two-key rollover” if you cannot use some three key combinations. (e.g., physical left command key + right command key + m)\nThere are two way to avoid the rollover problem.\nUse another keyboard which is N-key rollover. Use other key combinations. ","categories":"","description":"","excerpt":"It’s a hardware limitation of your keyboard called “two-key rollover” if you cannot use some three key combinations. (e.g., physical left command key + right command key + m)\nThere are two way to …","ref":"/docs/help/troubleshooting/cannot-use-some-key-combination/","tags":"","title":"Cannot use some three key combinations (key event is not fired)"},{"body":"sticky_modifier changes a key to a sticky modifier key.\n{ \"to\": [ { \"sticky_modifier\": { \"{modifier_name}\": \"on | off | toggle\" } } ] } Name Required Description {modifier_name} Optional - on always activates a sticky modifier.\n- off is vice versa.\n- toggle toggles a sticky modifier. toggle is suitable for most cases. Supported modifiers left_control left_shift left_option left_command right_control right_shift right_option right_command fn Examples { \"to\": [ { \"sticky_modifier\": { \"right_option\": \"toggle\" } } ] } Note You have to specify only one modifier.\nIf you want to activate multiple sticky modifiers, put multiple sticky_modifier as follows.\n{ \"to\": [ { \"sticky_modifier\": { \"left_control\": \"toggle\" } }, { \"sticky_modifier\": { \"left_shift\": \"toggle\" } } ] } ","categories":"","description":"","excerpt":"sticky_modifier changes a key to a sticky modifier key.\n{ \"to\": [ { \"sticky_modifier\": { \"{modifier_name}\": \"on | off | toggle\" } } ] } Name Required Description {modifier_name} Optional - on always …","ref":"/docs/json/complex-modifications-manipulator-definition/to/sticky-modifier/","tags":"","title":"to.sticky_modifier"},{"body":"software_function triggers a function that is implemented by software.\ncg_event_double_click Send double click event by software. set_mouse_cursor_position Move the mouse cursor to the specified point. iokit_power_management_sleep_system Causes an immediate system sleep. Table of Contents ","categories":"","description":"","excerpt":"software_function triggers a function that is implemented by software.\ncg_event_double_click Send double click event by software. set_mouse_cursor_position Move the mouse cursor to the specified …","ref":"/docs/json/complex-modifications-manipulator-definition/to/software_function/","tags":"","title":"to.software_function"},{"body":"If the following error message is appeared in log, your home directory owner ship is not valid.\n[warning] [grabber] /Users/.../karabiner.json is not owned by a valid user. The cause is that you are using an external storage and locating your home directory into the volume.\nYou have to enable ownership on the external volume by the following command in Terminal.app.\nsudo diskutil enableOwnership disk99999s99999 (Replace disk99999s99999 with your disk identifier which you can find by diskutil list command.)\n","categories":"","description":"","excerpt":"If the following error message is appeared in log, your home directory owner ship is not valid.\n[warning] [grabber] /Users/.../karabiner.json is not owned by a valid user. The cause is that you are …","ref":"/docs/help/troubleshooting/json-owner-is-invalid/","tags":"","title":"\"karabiner.json is not owned by a valid user\" error message in log"},{"body":"Karabiner-Elements provides a command line interface which provides the following functions.\nSwitch a profile by name. Show current profile name. Show all profile names. Set variables which are used in complex modifications. Copy the current profile to system default profile. (Administrator privilege is required.) Remove the system default profile. (Administrator privilege is required.) Lint complex_modifications.json. Display version. Usage Show help Run the following command in terminal.\n'/Library/Application Support/org.pqrs/Karabiner-Elements/bin/karabiner_cli' Result:\nA command line utility of Karabiner-Elements. Usage: karabiner_cli [OPTION...] --select-profile arg Select a profile by name. --show-current-profile-name Show current profile name --list-profile-names Show all profile names --set-variables arg Json string: {[key: string]: number|boolean|string} --copy-current-profile-to-system-default-profile Copy the current profile to system default profile. --remove-system-default-profile Remove the system default profile. --lint-complex-modifications complex_modifications.json Check complex_modifications.json --version Displays version. --version-number Displays version_number. --help Print help. Examples: karabiner_cli --select-profile 'Default profile' karabiner_cli --show-current-profile-name karabiner_cli --list-profile-names karabiner_cli --set-variables '{\"cli_flag1\":1, \"cli_flag2\":2}' Examples Switch profile Run the following command in terminal.\n'/Library/Application Support/org.pqrs/Karabiner-Elements/bin/karabiner_cli' --select-profile 'Default profile' Show current profile name Run the following command in terminal.\n'/Library/Application Support/org.pqrs/Karabiner-Elements/bin/karabiner_cli' --show-current-profile-name Show all profile names '/Library/Application Support/org.pqrs/Karabiner-Elements/bin/karabiner_cli' --list-profile-names ","categories":"","description":"","excerpt":"Karabiner-Elements provides a command line interface which provides the following functions.\nSwitch a profile by name. Show current profile name. Show all profile names. Set variables which are used …","ref":"/docs/manual/misc/command-line-interface/","tags":"","title":"Command line interface"},{"body":"\"manipulators\": [ { \"type\": \"basic\", \"from\": {...}, \"to\": [...], \"to_if_alone\": [...], \"to_if_held_down\": [...], \"to_after_key_up\": [...], \"to_delayed_action\": { \"to_if_invoked\": [...], \"to_if_canceled\": [...], }, \"conditions\": [...], \"parameters\": {...}, \"description\": \"Optional description for human\" }, ... ] Name Required Description type Required \"basic\" is specified from Required The name of key code, consumer key code or pointing button which you want to change to Optional Events which are sent when you press from key to_if_alone Optional Events which are sent when you press from key alone to_if_held_down Optional Events which are sent when you hold down from key to_after_key_up Optional Events which are sent after you release from key to_delayed_action Optional Events which are sent after 500 milliseconds at you press from key conditions Optional Manipulator is applied only if condition is matched (e.g., the frontmost application) parameters Optional Override parameters such as to_if_alone_timeout_milliseconds description Optional A human-readable comment Detail from event definition to event definition to_if_alone to_if_held_down to_after_key_up to_delayed_action conditions Other manipulators Manipulators which type is not \"basic\".\nmouse_motion_to_scroll Table of Contents ","categories":"","description":"","excerpt":"\"manipulators\": [ { \"type\": \"basic\", \"from\": {...}, \"to\": [...], \"to_if_alone\": [...], \"to_if_held_down\": [...], \"to_after_key_up\": [...], \"to_delayed_action\": { \"to_if_invoked\": [...], …","ref":"/docs/json/complex-modifications-manipulator-definition/","tags":"","title":"complex_modifications manipulator definition"},{"body":"You can switch profiles from menu bar. Manage profiles You can manage profiles from Profiles tab.\nPress Add new profile button to add new profile.\n","categories":"","description":"","excerpt":"You can switch profiles from menu bar. Manage profiles You can manage profiles from Profiles tab.\nPress Add new profile button to add new profile.\n","ref":"/docs/manual/operation/profiles/","tags":"","title":"Manage profiles"},{"body":"You can change the keyboard type (ANSI, ISO, JIS) from Virtual Keyboard tab.\nThe keyboard type is tied to the country code due to the macOS specification. And we have to log out to apply the keyboard type changes.\nSo, we recommend to assign each keyboard types to country code 0,1,2. And then, choose the country code when you want to change the current keyboard type.\nNote We have to log out after the keyboard type (ANSI, ISO, JIS) is changed to apply the changes.\nRelated articles Troubleshooting \u003e Input symbols are different from the key code name on non-ANSI keyboards ","categories":"","description":"","excerpt":"You can change the keyboard type (ANSI, ISO, JIS) from Virtual Keyboard tab.\nThe keyboard type is tied to the country code due to the macOS specification. And we have to log out to apply the keyboard …","ref":"/docs/manual/configuration/configure-keyboard-type/","tags":"","title":"Set keyboard type"},{"body":"to_after_key_up posts events when the from key is released.\nTip to_after_key_up is typically used to:\nUnset variables using set_variable Used with to_if_held_down and to.halt in order to define fallback behavior. Example The following json changes holding tab key to mission_control.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"tab\" }, \"to_after_key_up\": [ { \"key_code\": \"tab\" } ], \"to_if_held_down\": [ { \"key_code\": \"mission_control\", \"halt\": true } ] } ","categories":"","description":"","excerpt":"to_after_key_up posts events when the from key is released.\nTip to_after_key_up is typically used to:\nUnset variables using set_variable Used with to_if_held_down and to.halt in order to define …","ref":"/docs/json/complex-modifications-manipulator-definition/to-after-key-up/","tags":"","title":"to_after_key_up"},{"body":"to.modifiers is an array of the following strings.\nName Description caps_lock — left_command — left_control — left_option — left_shift — right_command — right_control — right_option — right_shift — fn — command Alias of left_command control Alias of left_control option Alias of left_option shift Alias of left_shift left_alt Alias of left_option (available since Karabiner-Elements 12.3.0) left_gui Alias of left_command (available since Karabiner-Elements 12.3.0) right_alt Alias of right_option (available since Karabiner-Elements 12.3.0) right_gui Alias of right_command (available since Karabiner-Elements 12.3.0) ","categories":"","description":"","excerpt":"to.modifiers is an array of the following strings.\nName Description caps_lock — left_command — left_control — left_option — left_shift — right_command — right_control — right_option — right_shift — fn …","ref":"/docs/json/complex-modifications-manipulator-definition/to/modifiers/","tags":"","title":"to.modifiers"},{"body":"Change an event if/unless the variable is the specified value.\nExample Change right_shift x2 to mission_control Virtual modifier Specification Tip variable_if and variable_unless are designed to use with set_variable. { \"type\": \"variable_if\", \"name\": \"variable name\", \"value\": variable value } Name Required Description type Required \"variable_if\" or \"variable_unless\". name Required Target variable name. value Required Target variable value. description Optional A human-readable comment Available types of value Type Example value Available since integer 0,1,2,… Karabiner-Elements 11.0.0 boolean true, false Karabiner-Elements 14.4.20 string “layer1”, “layer2” Karabiner-Elements 14.4.20 Comparison between different types Whenever the type of value is different, it is treated as having different contents.\n1 != true true != \"true\" Default value If the variable is not set to a value, the value is treated as 0. Confirm the current variable values You can see the current variable values by EventViewer \u003e Variables.\n","categories":"","description":"","excerpt":"Change an event if/unless the variable is the specified value.\nExample Change right_shift x2 to mission_control Virtual modifier Specification Tip variable_if and variable_unless are designed to use …","ref":"/docs/json/complex-modifications-manipulator-definition/conditions/variable/","tags":"","title":"variable_if, variable_unless"},{"body":"Karabiner-Elements shows an icon in menu bar which provides the following functions:\nSwitch profiles. Open Settings. Open EventViewer. Quit Karabiner-Elements. If you want to hide it, turn off “Show icon in menu bar” on Settings \u003e Misc tab.\n","categories":"","description":"","excerpt":"Karabiner-Elements shows an icon in menu bar which provides the following functions:\nSwitch profiles. Open Settings. Open EventViewer. Quit Karabiner-Elements. If you want to hide it, turn off “Show …","ref":"/docs/manual/configuration/configure-menu-bar-icon/","tags":"","title":"Configure icon in menu bar"},{"body":"Change an event if/unless the event is already changed by other manipulators.\nExample Change tab key to return_or_enter if the tab key is the physical tab key. (If the tab key is the result of modifying another key by simple modification, the key is ignored.)\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"tab\", \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"return_or_enter\" } ], \"conditions\": [ { \"type\": \"event_changed_if\", \"value\": false } ] } Specification { \"type\": \"event_changed_if\", \"value\": true } Name Required Description type Required \"event_changed_if\" or \"event_changed_unless\" value Required true or false description Optional A human-readable comment Tip event_changed_unless is designed to prevent Function Keys Modifications from changing fx keys which are changed in Complex Modifications (e.g., Change command+e to f2).\nIf you use event_changed_if or event_changed_unless in Complex Modifications, your rule is ignored for keys which are changed in Simple Modifications.\n","categories":"","description":"","excerpt":"Change an event if/unless the event is already changed by other manipulators.\nExample Change tab key to return_or_enter if the tab key is the physical tab key. (If the tab key is the result of …","ref":"/docs/json/complex-modifications-manipulator-definition/conditions/event-changed/","tags":"","title":"event_changed_if, event_changed_unless"},{"body":" Note This page is for macOS 10.15 Catalina, not macOS 11 Big Sur or later. “.Karabiner-VirtualHIDDevice-Manager” is usually shown in Security \u0026 Privacy System Preferences when macOS requires your approval.\nHowever, “Placeholder Developer” will be shown due to a macOS issue if you meet all of the following criteria:\nYou are using macOS Catalina (10.15) Multiple system software are waiting your approval. Workarounds In this case, you can choose one of the following three options to use Karabiner-Elements:\nUpgrade to macOS Big Sur (11.0) or later. Downgrade to Karabiner-Elements v12.10.0.\nDownload the package from the above page, and then re-install Karabiner-Elements from the downloaded package. Allow “Placeholder Developer”. Info: This issue is solved with macOS Big Sur (11.0) The name is shown properly on macOS Big Sur.\n","categories":"","description":"","excerpt":" Note This page is for macOS 10.15 Catalina, not macOS 11 Big Sur or later. “.Karabiner-VirtualHIDDevice-Manager” is usually shown in Security \u0026 Privacy System Preferences when macOS requires your …","ref":"/docs/help/troubleshooting/placeholder-developer/","tags":"","title":"Placeholder Developer is shown in Security \u0026 Privacy System Preferences"},{"body":"You can confirm log messages on Log tab.\nAdvanced topic The log files are placed at:\nSystem logs\n/var/log/karabiner/grabber.log /var/log/karabiner/observer.log /var/log/karabiner/virtual_hid_device_service.log User logs\n~/.local/share/karabiner/log/console_user_server.log ~/.local/share/karabiner/log/grabber_agent.log ~/.local/share/karabiner/log/observer_agent.log /var/log/karabiner/session_monitor.{uid}.log ","categories":"","description":"","excerpt":"You can confirm log messages on Log tab.\nAdvanced topic The log files are placed at:\nSystem logs\n/var/log/karabiner/grabber.log /var/log/karabiner/observer.log …","ref":"/docs/manual/operation/log/","tags":"","title":"Show log messages"},{"body":"Karabiner-Elements stores configuration to a json file which is located ~/.config/karabiner/karabiner.json\nAbout symbolic link If you want to move karabiner.json to another place and make symbolic link, make a symbolic link to ~/.config/karabiner directory instead of karabiner.json.\nWarning Do not make a symlink to karabiner.json directly.\nKarabiner-Elements will fail to detect the configuration file update and fail to reload the configuration if karabiner.json is a symbolic link.\nMaking symbolic link example The following command allows you to put karabiner.json on ~/Dropbox/private.\nmv ~/.config/karabiner ~/Dropbox/private ln -s ~/Dropbox/private/karabiner ~/.config Note You have to restart karabiner_console_user_server process by the following command after you made a symlink in order to tell Karabiner-Elements that the parent directory is changed.\nlaunchctl kickstart -k gui/`id -u`/org.pqrs.karabiner.karabiner_console_user_server ","categories":"","description":"","excerpt":"Karabiner-Elements stores configuration to a json file which is located ~/.config/karabiner/karabiner.json\nAbout symbolic link If you want to move karabiner.json to another place and make symbolic …","ref":"/docs/manual/misc/configuration-file-path/","tags":"","title":"The location of the configuration file"},{"body":"to_delayed_action posts events after 500 milliseconds from the from key is pressed.\nto_delayed_action.to_if_invoked An array of to events that will be sent if no other key is pressed after the from key is pressed. to_delayed_action.to_if_canceled An array of to events that will be sent if another key is pressed after the from key is pressed before to_delayed_action.to_if_invoked is sent. Tip to_delayed_action is typically used to:\nDouble tap key (e.g., change right_shift x2) 2 stroke keys such as C-x of Emacs Mode. Example The following json provide Quit application by pressing command-q twice.\n[ { \"type\": \"basic\", \"conditions\": [ { \"type\": \"variable_if\", \"name\": \"command-q\", \"value\": 1 } ], \"from\": { \"key_code\": \"q\", \"modifiers\": { \"mandatory\": [\"command\"], \"optional\": [\"caps_lock\"] } }, \"to\": [ { \"key_code\": \"q\", \"modifiers\": \"left_command\" } ] }, { \"type\": \"basic\", \"from\": { \"key_code\": \"q\", \"modifiers\": { \"mandatory\": [\"command\"], \"optional\": [\"caps_lock\"] } }, \"to\": [ { \"set_variable\": { \"name\": \"command-q\", \"value\": 1 } } ], \"to_delayed_action\": { \"to_if_invoked\": [ { \"set_variable\": { \"name\": \"command-q\", \"value\": 0 } } ], \"to_if_canceled\": [ { \"set_variable\": { \"name\": \"command-q\", \"value\": 0 } } ] } } ] Parameters You can adjust the milliseconds invoking to_delayed_action by parameters \u003e basic.to_delayed_action_delay_milliseconds as follows.\n{ \"type\": \"basic\", \"from\": ..., \"to_delayed_action\": ..., \"parameters\": { \"basic.to_delayed_action_delay_milliseconds\": 1000 } } ","categories":"","description":"","excerpt":"to_delayed_action posts events after 500 milliseconds from the from key is pressed.\nto_delayed_action.to_if_invoked An array of to events that will be sent if no other key is pressed after the from …","ref":"/docs/json/complex-modifications-manipulator-definition/to-delayed-action/","tags":"","title":"to_delayed_action"},{"body":"to.lazy is true or false. The default value is false.\nIf to.lazy is true and to.key_code is modifier flag such as \"key_code\": \"left_shift\", the to.key_code acts as lazy modifier.\nThe lazy modifier does not send own key events until another key is pressed together.\nTip The lazy modifier is designed using with to_if_alone or key combinations such as changing left_control + h to delete_or_backspace in order to suppress unnecessary modifier key events. Example The following json changes:\nleft_control to the lazy left control left_control + m to return_or_enter Behavior of the json:\nThe left_control key event will not be sent when you press left_control alone. Only the return_or_enter key event will be sent when you press left_control + m. You can use left_control for other keys such as left_control + a, left_control + b, etc. [ { \"type\": \"basic\", \"from\": { \"key_code\": \"left_control\" }, \"to\": [ { \"key_code\": \"left_control\", \"lazy\": true } ] }, { \"type\": \"basic\", \"from\": { \"key_code\": \"m\", \"modifiers\": { \"mandatory\": [\"left_control\"], \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"return_or_enter\" } ] } ] ","categories":"","description":"","excerpt":"to.lazy is true or false. The default value is false.\nIf to.lazy is true and to.key_code is modifier flag such as \"key_code\": \"left_shift\", the to.key_code acts as lazy modifier.\nThe lazy modifier …","ref":"/docs/json/complex-modifications-manipulator-definition/to/lazy/","tags":"","title":"to.lazy"},{"body":"You can change the icons that appear in the Finder, Launchpad, Dock, etc from Settings \u003e UI.\nNote The icon in Dock will not reflect changes while the application is open. So, you should close and reopen the application to update the icon in Dock. ","categories":"","description":"","excerpt":"You can change the icons that appear in the Finder, Launchpad, Dock, etc from Settings \u003e UI.\nNote The icon in Dock will not reflect changes while the application is open. So, you should close and …","ref":"/docs/manual/misc/change-app-icon/","tags":"","title":"Change app icon"},{"body":"Privacy Security and privacy protection is one of the most important points of Karabiner-Elements architecture design.\nOf course, Karabiner-Elements does not collect any of your input data, your configuration data, nor your usage statistics.\nData not collected Karabiner-Elements does not transmit your data externally. The following data is never transmitted outside your Mac:\nYour keystrokes Your configuration data Your usage statistics And all other data except Karabiner-Elements version information. About Input Monitoring Karabiner-Elements exclusively receives input events from your keyboard, and then modifies them. To do this, Karabiner-Elements requires your Input Monitoring permissions approval.\nKeystrokes captured with this privilege are processed entirely on your Mac. And because the process is protected by administrative privileges, keystrokes cannot be intercepted at by other applications on your Mac.\nSpecifically, the processes with administrative privileges are as follows:\nkarabiner_grabber: This is the most core process in Karabiner-Elements that captures and modifies keystrokes. karabiner_observer: This process monitors input events on non-capturing devices and controls karabiner_grabber so that it does not start capturing while the very keystrokes are being made. Note: Karabiner-EventViewer operates with lower privileges than karabiner_grabber and karabiner_observer. Since it runs with user privileges, it cannot receive keystrokes during password inputs or similar actions when Secure Keyboard Entry is enabled.\nInput event manipulation After capturing keystrokes, the karabiner_grabber process modifies input events based on user settings. Modifying input events is also performed with security considerations in mind.\nTo prevent the addition of malicious input from other applications, karabiner_grabber performs closed operations within the process, which has administrative privileges. And the karabiner_grabber process does not knowingly alter, insert or manipulate any keystrokes other than as configured and expected by the user.\nNote: Some combinations, such as fn+arrow keys, are implicitly changed. For a list, please see Implicit behavior.\nUser data and files Karabiner-Elements and any bundled softwares, e.g., EventViewer, do not access or modify user data and files, except in the following data:\nUser files and data referenced by Karabiner-Elements:\nConfiguration files specific to the application. The keyboard type configuration (ANSI, ISO, JIS) in the system settings. The “Use F1, F2, etc. keys as standard function keys” configuration in the system settings. About karabiner_machine_identifier Since Karabiner-Elements v14.99.2, a unique random ID called karabiner_machine_identifier is generated for each machine during Karabiner-Elements installation. This ID may be included in the configuration file karabiner.json when machine-specific settings are made. For instance, when the Multitouch Extension is enabled, the following content is added to karabiner.json, and the string starting with krbn- is the karabiner_machine_identifier.\nThis string is completely random and does not contain any unique information about the user or the machine. In other words, this ID is not linked to information like your Apple ID or Mac’s serial number. Therefore, it is a safe ID to share with others, and there is no need to mask it when you share karabiner.json with others.\nOf course, Karabiner-Elements never collect this ID.\nTechnical Information The karabiner_machine_identifier is in the format krbn-{UUID v4}.\nThe generated ID is saved in /Library/Application Support/org.pqrs/tmp/karabiner_machine_identifier.json as the following forms.\n{ \"karabiner_machine_identifier\": \"krbn-818632bf-2a88-4ac0-ad0b-4524721c217b\" } Data being collected The only data we are collecting is Karabiner-Elements version information.\nWe use the data only for checking updates, and we do not share these data with others. How we receive the data The version information will be sent in order to check updates when automatic update is enabled, or when you press the update button manually.\nThe URLs to send the version information are as follows:\nhttps://appcast.pqrs.org/karabiner-elements-appcast.xml https://appcast.pqrs.org/karabiner-elements-appcast-devel.xml You can change the automatic update setting in Update tab.\nDetail appcast.pqrs.org receives the version information like follows:\n150.249.243.141 - - [13/Feb/2021:18:37:14 +0900] \"GET /karabiner-elements-appcast.xml HTTP/2.0\" 200 2389 \"-\" \"Karabiner-Elements/13.3.0 Sparkle/1.24.0\" \"-\" 150.249.243.141 - - [13/Feb/2021:19:26:15 +0900] \"GET /karabiner-elements-appcast-devel.xml HTTP/2.0\" 200 740 \"-\" \"Karabiner-Elements/13.3.0 Sparkle/1.24.0\" \"-\" The received data contains:\nName Example Access source IP address 150.249.243.141 Access time 13/Feb/2021:18:37:14 +0900 Karabiner-Elements version Karabiner-Elements/13.3.0 Sparkle/1.24.0 Related documents Security ","categories":"","description":"","excerpt":"Privacy Security and privacy protection is one of the most important points of Karabiner-Elements architecture design.\nOf course, Karabiner-Elements does not collect any of your input data, your …","ref":"/docs/privacy/","tags":"","title":"Privacy"},{"body":"If you are using old Karabiner-Elements (12.x.x or earlier) on macOS Catalina or later, the following alert will be shown.\nPlease upgrade Karabiner-Elements 13.0.0 or later.\n","categories":"","description":"","excerpt":"If you are using old Karabiner-Elements (12.x.x or earlier) on macOS Catalina or later, the following alert will be shown.\nPlease upgrade Karabiner-Elements 13.0.0 or later.\n","ref":"/docs/manual/misc/legacy-system-extension/","tags":"","title":"About \"Legacy System Extension\" alert"},{"body":"Karabiner-Elements has a setting to disable caps lock LED control.\nIf your caps lock LED is not working properly, this setting may be enabled, so check the Manipulate caps lock LED setting in the Devices tab.\n","categories":"","description":"","excerpt":"Karabiner-Elements has a setting to disable caps lock LED control.\nIf your caps lock LED is not working properly, this setting may be enabled, so check the Manipulate caps lock LED setting in the …","ref":"/docs/help/troubleshooting/caps-lock-led-not-working/","tags":"","title":"Caps Lock LED not working"},{"body":"Reporting Bugs, Feature requests Please post an issue to GitHub.\nKarabiner-Elements KE-complex_modifications (About complex modifications) Required information with bug reports Please fill your information when you send bug reports:\nRequired information macOS version: Karabiner version:\n(You can confirm the version in “Update” tab in Karabiner Settings.) Your Mac hardware: Your keyboard hardware: Example:\nmacOS version: macOS 14.1.2 Karabiner version: Karabiner-Elements 14.13.0 Your Mac hardware: M2 MacBook Air Your keyboard hardware: Das Keyboard 4 Professional for Mac Mechanical Keyboard Other Send a message to author of Karabiner-Elements.\nNote I’m sorry I cannot spend enough time to reply for all mails since I’m receiving a lot mails.\nGitHub is suitable place to post it unless you have a private question. ","categories":"","description":"","excerpt":"Reporting Bugs, Feature requests Please post an issue to GitHub.\nKarabiner-Elements KE-complex_modifications (About complex modifications) Required information with bug reports Please fill your …","ref":"/docs/contact/","tags":"","title":"Contact"},{"body":"You can export and import configuration by copying karabiner.json file to another machine.\nExport Open config folder from Karabiner-Elements Settings \u003e Misc. Configuration folder will be opened by Finder. Copy the karabiner.json file. Import Open config folder from Karabiner-Elements Settings \u003e Misc. Replace karabiner.json with the exported file. (The configuration file will be reloaded automatically.) ","categories":"","description":"","excerpt":"You can export and import configuration by copying karabiner.json file to another machine.\nExport Open config folder from Karabiner-Elements Settings \u003e Misc. Configuration folder will be opened by …","ref":"/docs/manual/operation/export/","tags":"","title":"Export and import configuration"},{"body":"Karabiner-Elements configuration generators:\nGokuRakuJoudo Goku generates karabiner.json from well designed edn format file. Karabiner Complex Modification The web UI for creating json of complex modification rules. Karabiner::CompModGenerator Raku module for easily bulk generating and regenerating complex modification from pre-defined templates. Jsonnet A data templating language as a simple extension of JSON to generate config data with the benefit to organize, simplify, unify, and manage sprawling configurations. karabiner.ts Write complex modification rules in TypeScript with strong typing. ","categories":"","description":"","excerpt":"Karabiner-Elements configuration generators:\nGokuRakuJoudo Goku generates karabiner.json from well designed edn format file. Karabiner Complex Modification The web UI for creating json of complex …","ref":"/docs/json/external-json-generators/","tags":"","title":"External JSON generators"},{"body":"to.repeat is true or false. The default value is true.\nThe key repeating will be suppressed if to.repeat is false.\nNote You have to set repeat in the last to event as follows if you have multiple to events and want to set to.repeat false.\n{ \"to\": [ { \"key_code\": \"h\" }, { \"key_code\": \"e\" }, { \"key_code\": \"l\" }, { \"key_code\": \"l\" }, { \"key_code\": \"o\", \"repeat\": false } ] } Tip to.repeat affects key_up event sending timing as follows.\nIf to.repeat is true: key_up event is sent when you release the key. If to.repeat is false: key_down and key_up events are sent when you press the key. ","categories":"","description":"","excerpt":"to.repeat is true or false. The default value is true.\nThe key repeating will be suppressed if to.repeat is false.\nNote You have to set repeat in the last to event as follows if you have multiple to …","ref":"/docs/json/complex-modifications-manipulator-definition/to/repeat/","tags":"","title":"to.repeat"},{"body":"There are several settings that cannot be enabled by default in the GUI to prevent improper configuration which breaks macOS operation.\nAlthough never recommended, enabling Unsafe Configuration from the Pro tab allows you the following operations.\nIf you want to enable the unsafe configuration, remember how to start up your Mac in safe mode. You can restore the settings in safe mode even if you make a mistake.\nHow to enable unsafe configuration Enabled operations Allow to modify Apple pointing devices Before:\nAfter:\nAllow to change the mouse button 1 It is possible to change the left click.\n","categories":"","description":"","excerpt":"There are several settings that cannot be enabled by default in the GUI to prevent improper configuration which breaks macOS operation.\nAlthough never recommended, enabling Unsafe Configuration from …","ref":"/docs/manual/operation/about-unsafe-configuration/","tags":"","title":"About Unsafe Configuration"},{"body":"If you face a problem and you want to revert previous version, please downgrade Karabiner-Elements as follows.\nUninstall Karabiner-Elements from uninstaller. Download a previous version from here. Install again. Advanced topic The first uninstallation is required to remove the virtual driver. Since virtual drivers cannot be directly downgraded, if you want to install an older version, you need to remove a newer version beforehand. ","categories":"","description":"","excerpt":"If you face a problem and you want to revert previous version, please downgrade Karabiner-Elements as follows.\nUninstall Karabiner-Elements from uninstaller. Download a previous version from here. …","ref":"/docs/manual/operation/downgrade/","tags":"","title":"Downgrade"},{"body":" Karabiner-Elements is an open source software and you can use it without any purchases.\nSupporting this project This project accepts your funding via GitHub Sponsors or PayPal.\nFor donors I appreciate all donors. I received your donations!\nI’m afraid I don’t have enough time to reply for donors.\n(I’m giving priority to develop Karabiner-Elements at the moment.)\nDec 17, 2023\nTakayama Fumihiko Monthly or One-time (GitHub Sponsors) Takayama Fumihiko @tekezo Open GitHub Sponsors page One-time (PayPal) Open PayPal Payments Form (Pay $10 for Karabiner-Elements) Note: This is effectively a donation but it has taken the form of software fee because of Japanese law and the constraints on government regulation. Sponsors Thank you for supporting Karabiner-Elements! JavaScript is required to show sponsors. ","categories":"","description":"","excerpt":" Karabiner-Elements is an open source software and you can use it without any purchases.\nSupporting this project This project accepts your funding via GitHub Sponsors or PayPal.\nFor donors I …","ref":"/docs/pricing/","tags":"","title":"Pricing"},{"body":"If you manually registered Karabiner-Elements to Open at Login, the settings window will always appear at startup.\nKarabiner-Elements will start automatically via launchd even if it is not in Open at Login, so remove it from your Open at Login.\nOpen System Settings. Open General \u003e Login Items. Remove Karabiner-Elements from Open at Login. Caution Do not disable Karabiner-Elements.app in Allow in the Background. It’s a required setting for Karabiner-Elements to work. ","categories":"","description":"","excerpt":"If you manually registered Karabiner-Elements to Open at Login, the settings window will always appear at startup.\nKarabiner-Elements will start automatically via launchd even if it is not in Open at …","ref":"/docs/help/troubleshooting/preferences-window-shown-at-login/","tags":"","title":"Settings window is shown at login"},{"body":"to.halt is true or false. The default value is false.\nThe typical usage of to.halt is to cancel to_after_key_up if to_if_alone or to_if_held_down is triggered.\nPut \"halt\": true into to_if_alone or to_if_held_down if you want to suppress to_after_key_up when to_if_alone or to_if_held_down is triggered.\nExample The following json changes holding tab key to mission_control.\nThe halt in to_if_held_down suppresses to_after_key_up after mission_control is sent.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"tab\" }, \"to_after_key_up\": [ { \"key_code\": \"tab\" } ], \"to_if_held_down\": [ { \"key_code\": \"mission_control\", \"halt\": true } ] } ","categories":"","description":"","excerpt":"to.halt is true or false. The default value is false.\nThe typical usage of to.halt is to cancel to_after_key_up if to_if_alone or to_if_held_down is triggered.\nPut \"halt\": true into to_if_alone or …","ref":"/docs/json/complex-modifications-manipulator-definition/to/halt/","tags":"","title":"to.halt"},{"body":"This is the intended behavior.\nThe key code name using in Karabiner-Elements is HID usage name. This is close to the physical key location on the ANSI layout keyboard.\nFor this reason, there are mismatches of symbols actually input and key code names on non-ANSI keyboards.\nDetermining which characters are to be input by keyboard event is the later step in the processing flow of macOS. Karabiner-Elements changes input events on a layer closer to the hardware, which is why it works like this.\nPlease use key code names that matches your layout.\nANSI layout JIS layout Key code table Layout Symbols Key code name JIS @ open_bracket JIS [ close_bracket JIS ] backslash JIS \\ international3 JIS _ international1 Related articles Manual \u003e Configuration \u003e Set keyboard type ","categories":"","description":"","excerpt":"This is the intended behavior.\nThe key code name using in Karabiner-Elements is HID usage name. This is close to the physical key location on the ANSI layout keyboard.\nFor this reason, there are …","ref":"/docs/help/troubleshooting/symbols-with-non-ansi-keyboard/","tags":"","title":"Input symbols are different from the key code name on non-ANSI keyboards"},{"body":"to.hold_down_milliseconds is an integer value. The default value is 0.\nThe value is an interval of key_down and key_up when key_down and key_up events are sent at the same time such as multiple to events.\nNote Generally to.hold_down_milliseconds is used with \"key_code\": \"caps_lock\". Example The following json changes caps_lock key to sending caps_lock key_down, wait 200 milliseconds, caps_lock key_up.\n{ \"type\": \"basic\", \"from\": { \"key_code\": \"caps_lock\", \"modifiers\": { \"optional\": [\"any\"] } }, \"to\": [ { \"key_code\": \"caps_lock\", \"hold_down_milliseconds\": 200 }, { \"key_code\": \"vk_none\" } ] } ","categories":"","description":"","excerpt":"to.hold_down_milliseconds is an integer value. The default value is 0.\nThe value is an interval of key_down and key_up when key_down and key_up events are sent at the same time such as multiple to …","ref":"/docs/json/complex-modifications-manipulator-definition/to/hold-down-milliseconds/","tags":"","title":"to.hold_down_milliseconds"},{"body":"This was discovered when using an MX Keys keyboard with the “Logi Options+” software. While Karabiner Elements is running, the Logitech specific function keys (such as Fn-esc to toggle between function keys and media keys and f1, f2, f3 to switch between inputs) are not recognized.\nThe solution is to edit karabiner.json such that the \"fn_function_keys\" array is empty:\n\"fn_function_keys\": [] Credit: https://github.com/pqrs-org/Karabiner-Elements/issues/1450#issuecomment-1013932206\n","categories":"","description":"","excerpt":"This was discovered when using an MX Keys keyboard with the “Logi Options+” software. While Karabiner Elements is running, the Logitech specific function keys (such as Fn-esc to toggle between …","ref":"/docs/help/troubleshooting/logitech-logi-options-plus-compatibility/","tags":"","title":"Compatibility with Logitech Logi Options+: Fn keys"},{"body":" Karabiner-Elements A powerful and stable keyboard customizer for macOS. Download v15.0.0 Toggle Dropdown Download v15.0.0 For macOS 15 Sequoia For macOS 14 Sonoma For macOS 13 Ventura Download v14.13.0 For macOS 12 Monterey For macOS 11 Big Sur Download v13.7.0 For macOS 10.15 Catalina (10.15.6 or later) Download v12.10.0 For macOS 10.15 Catalina For macOS 10.14 Mojave For macOS 10.13 High Sierra For macOS 10.12 Sierra Download v11.6.0 For macOS 10.11 El Capitan Download v10.22.0 For macOS 10.11 El Capitan For macOS 10.10 Yosemite For macOS 10.9 Mavericks Learn more Privacy Supported systems macOS 15 Sequoia\nmacOS 14 Sonoma\nmacOS 13 Ventura\nBoth Intel-based Macs and Apple Silicon Macs are supported. Predefined rules by community Release notes GitHub Sponsor Easy to use You can configure simple key mappings from GUI.\nRead more\nPowerful There are many powerful, predefined rules.\nDiamond cursor Emacs key bindings anywhere Vi key bindings Prevent unintended command-q Mouse keys You can import them from the Internet.\nRead more\nFlexible You can write your own rules if you want to modify existing rules or create new rules from scratch.\nRead more\nSponsors Thank you for supporting Karabiner-Elements! JavaScript is required to show sponsors. ","categories":"","description":"","excerpt":" Karabiner-Elements A powerful and stable keyboard customizer for macOS. Download v15.0.0 Toggle Dropdown Download v15.0.0 For macOS 15 Sequoia For macOS 14 Sonoma For macOS 13 Ventura Download …","ref":"/","tags":"","title":"Karabiner-Elements"}]
\ No newline at end of file