Where apps hide your files

Finding karabiner.json

Updated 2026-10-28 · 5 min read

Karabiner-Elements stores everything you set up in one JSON file inside a hidden folder, which is why Finder and Spotlight never show it. This page gives the path, the folders around it and the safe way to copy it.

The path

Your main Karabiner-Elements configuration is this file:

~/.config/karabiner/karabiner.json

Karabiner-Elements watches that file and reloads it automatically when it changes. The folder around it holds the rest of your setup:

~/.config/karabiner/
~/.config/karabiner/assets/complex_modifications/
~/.config/karabiner/automatic_backups/
~/.local/share/karabiner/log/console_user_server.log

The configuration, rule and log paths come from the Karabiner-Elements documentation. The automatic_backups folder comes from its release notes (version 12.2.0): before the app rewrites karabiner.json, it saves a copy named karabiner_YYYYMMDD.json there, at most one per day.

Open it

The easiest route is inside the app. Open Karabiner-Elements Settings, go to Misc, and use the button that opens the configuration folder. Finder opens it for you.

By hand, the folder starts with a dot, so Finder hides it. In Finder press ⇧⌘G (Go > Go to Folder) and paste ~/.config/karabiner. You can also press ⇧⌘. in any Finder window to show hidden items. In Terminal:

open ~/.config/karabiner

What is in the folder

Item	What it is
karabiner.json	Your profiles, simple modifications, complex modifications, device settings and function key choices
assets/complex_modifications/	Rule files you imported or wrote yourself, offered under Settings > Complex Modifications > Add predefined rule
automatic_backups/	Dated copies such as karabiner_20261028.json, saved before the app changed the file

Inside karabiner.json the settings are grouped by profile. If you only ever see one profile in Settings, the file has one entry in its profiles list. Imported rules are copied into the profile, so the file in assets/complex_modifications/ is only the source you imported from.

Back it up or move it to a new Mac

Karabiner's own export route is simple: open the configuration folder from Settings > Misc, copy karabiner.json, and keep it somewhere safe. To import on another Mac, install Karabiner-Elements, open the same folder from Settings, and replace karabiner.json with your copy. The app reloads it automatically.

If you also wrote your own rule files, copy assets/complex_modifications/ too, so you can re-import or edit them later.

Uninstalling Karabiner-Elements does not remove ~/.config/karabiner or ~/.local/share/karabiner, according to its uninstall page, so a reinstall on the same Mac finds your settings again. A single misplaced character in a hand-edited file can stop the whole file loading, so copy it before you edit.

Keep it in a dotfiles repo

Many people version ~/.config/karabiner in Git. Two rules from the official documentation matter here. Karabiner-Elements detects changes by watching the parent directory ~/.config/karabiner, so if you recreate that directory, change detection fails. And if you want the folder to live elsewhere, link the directory rather than the file, because changes to a karabiner.json that is itself a symbolic link are not detected. The documentation's own example moves the folder into Application Support and links it back:

mkdir -p "$HOME/Library/Application Support/org.pqrs/config"
mv ~/.config/karabiner "$HOME/Library/Application Support/org.pqrs/config"
ln -s "$HOME/Library/Application Support/org.pqrs/config/karabiner" ~/.config
launchctl kickstart -k gui/$(id -u)/org.pqrs.service.agent.Karabiner-Console-User-Server

The last line restarts the background process that watches the file; until you run it, edits in the new location are not picked up. If you put the folder in Desktop, Documents, Downloads or another protected place, the documentation says to give the Karabiner-Elements apps Full Disk Access.

Errors and logs

If an edit does not take effect, the parse error is written to:

~/.local/share/karabiner/log/console_user_server.log

You can also read it in Karabiner-Elements under Settings > Log. Karabiner-EventViewer is useful for checking which key codes a keyboard actually sends, which is what you need when writing a rule by hand.

Restoring after a bad edit

If a hand edit leaves the keyboard doing nothing sensible, the quickest recovery is to put a known good copy back. Open the folder from Settings > Misc, move the broken karabiner.json to your Desktop, then either paste in the copy you exported earlier or duplicate the newest file in automatic_backups, move the duplicate up into ~/.config/karabiner and rename it karabiner.json. Work on a copy, never on the only copy. Karabiner reloads on its own, so you can test straight away.

A quick check before you save any hand edit: standard JSON does not allow trailing commas or comments, and a stray comma is a common reason the file stops loading. The log entry usually says where parsing failed.

Testing without your configuration

The documentation does not describe a reset. A reversible test is to move karabiner.json to your Desktop (do not delete it), check how the keyboard behaves without it, and move it back if your configuration was not the cause.

Why a normal search misses it

Spotlight skips hidden dot-folders, so karabiner.json never appears when you search for it. The log lives under ~/.local/share, also hidden. The app itself sits in /Applications, but its settings do not.

Finding it again quickly

Karabiner's whole configuration is a folder you will want to reach at odd moments, such as after a macOS reinstall or when a keyboard stops behaving. Everywhere lists file names inside hidden folders like .config and .local that Spotlight leaves out, so typing karabiner_ brings up the dated backups and karabiner.json shows the live file, wherever you linked it. Press ⌘↵ to reveal the one you want in Finder. It matches names only, so it will not find a rule by what is written inside the JSON.

Common questions

Where is karabiner.json on a Mac?

In ~/.config/karabiner/karabiner.json. The .config folder is hidden, so use Go > Go to Folder (⇧⌘G) in Finder or run open ~/.config/karabiner in Terminal.

How do I back up my Karabiner-Elements settings?

Open the configuration folder from Settings > Misc and copy karabiner.json. Copy assets/complex_modifications as well if you keep your own rule files.

Can I symlink karabiner.json?

Not the file itself. Karabiner's documentation says changes are not detected when karabiner.json is a symbolic link, so link the whole ~/.config/karabiner directory instead and restart the console user server as the documentation shows.

Where are the Karabiner-Elements logs?

In ~/.local/share/karabiner/log/console_user_server.log, and also inside the app under Settings > Log.