nix-darwin 単独でキーマッピングを変更する - Karabiner を使わずに宣言的記述で設定

nix-darwin 単独でキーマッピングを変更する Karabiner を使わずに宣言的記述で設定 ryu 2026/2/5 Nix 日本語コミュニティゼミ

Nix 日本語コミュニティゼミ 自己紹介: ryu バックグラウンド: 非 IT 系企業の社内 SE エンジニア歴 2 年 Nix が好き GitHub: ryuryu333 Zenn: trifolium 2026/2/5 ryu(@ryu_trifolium) 2

Nix 日本語コミュニティゼミ nix-darwin でキーマッピングを変更する方法 nix-darwin - system.keyboard.* 単純な変更のみ、利用可能なオプションが少ない（5種） 、 、 nonUS.remapTilde remapCapsLockToControl remapCapsLockToEscape swapLeftCommandAndLeftAlt swapLeftCtrlAndFn 、 Karabiner-Elements 設定ファイル（ ）が別途必要 nix-darwin 単独で設定が完結しない karabiner.json 2026/2/5 ryu(@ryu_trifolium) 3

• https://nix-darwin.github.io/nix-darwin/manual/#opt-system.keyboard.enableKeyMapping
• https://karabiner-elements.pqrs.org/

Nix 日本語コミュニティゼミ nix-darwin で設定を完結させたい だと機能不足 どうすればいいのか... ↓ 取り敢えずソースコードを見てみよう system.keyboard.* 2026/2/5 ryu(@ryu_trifolium) 4

Nix 日本語コミュニティゼミ

それっぽい関数を発見

nix-darwin/modules/system/keyboard.nix
options = {
...
system.keyboard.userKeyMapping = mkOption {
internal = true;
type = types.listOf (types.attrsOf types.int);
default = [];
description = ''
List of keyboard mappings to apply, for more information see
<https://developer.apple.com/library/content/technotes/tn2450/_index.html>.
'';
};
};

2026/2/5 ryu(@ryu_trifolium)

5

• https://github.com/nix-darwin/nix-darwin/blob/master/modules/system/keyboard.nix

Nix 日本語コミュニティゼミ 利用方法を探す - 1 リファレンスになぜか記載がない →ソースコードから利用例を観察する config = { ... system.keyboard.userKeyMapping = [ (mkIf cfg.remapCapsLockToControl { HIDKeyboardModifierMappingSrc = 30064771129; HIDKeyboardModifierMappingDst = 30064771296; }) ... ] }; 2026/2/5 ryu(@ryu_trifolium) 6

• https://nix-darwin.github.io/nix-darwin/manual/#opt-system.keyboard.enableKeyMapping

Nix 日本語コミュニティゼミ

利用方法を探す - 2

description に書かれているリンクを見てみる
→
コマンドを利用した Remapping Keys のガイド
記載されていたコマンド例
hidutil

hidutil property --set '{"UserKeyMapping":
[{"HIDKeyboardModifierMappingSrc":0x700000004,
"HIDKeyboardModifierMappingDst":0x700000005}]}'

2026/2/5 ryu(@ryu_trifolium)

7

• https://developer.apple.com/library/content/technotes/tn2450/_index.html

Nix 日本語コミュニティゼミ

hidutil とは

HID（Human Interface Device）デバイスのプロパティを
確認・変更するためのコマンドラインツール
OS 標準の機能だけでキーの入れ替えが可能
PC を再起動するとリセットされる

hidutil property --set '{"UserKeyMapping":
[{"HIDKeyboardModifierMappingSrc":0x700000004,
"HIDKeyboardModifierMappingDst":0x700000005}]}'

2026/2/5 ryu(@ryu_trifolium)

8

Nix 日本語コミュニティゼミ system.keyboard.userKeyMapping OS 標準の仕組みである を利用してキーマッピングを 変更する nix-darwin の設定 以下のようなリストを渡す Src のキーが Dst のキーとして扱われるようになる hidutil ({ HIDKeyboardModifierMappingSrc = 30064771129; HIDKeyboardModifierMappingDst = 30064771296; }) 2026/2/5 ryu(@ryu_trifolium) 9

Nix 日本語コミュニティゼミ 設定方法を探る が true の場合 Src = 30064771299、Dst = 30064771298 が指定されている system.keyboard.swapLeftCommandAndLeftAlt (mkIf cfg.swapLeftCommandAndLeftAlt { HIDKeyboardModifierMappingSrc = 30064771299; HIDKeyboardModifierMappingDst = 30064771298; }) は 16 進数でキーを指定する では 10 進数になっている 30064771299（10 進数） = 0x7000000E3（16 進数） hidutil system.keyboard.userKeyMapping 2026/2/5 ryu(@ryu_trifolium) 10

Nix 日本語コミュニティゼミ 0x7000000E3 この値の意味 The keys take a hexadecimal value that consists of 0x700000000 or’d with the desired keyboard usage value Remapping Keys in macOS 10.12 Sierra より → キーを表す数値が決まっている Usage Usage ID (hex) Keyboard a and A 0x04 Keyboard b and B 0x05 2026/2/5 ryu(@ryu_trifolium) 11

• https://developer.apple.com/library/archive/technotes/tn2450/_index.html

Nix 日本語コミュニティゼミ 0x7000000E3 前半の数列の意味 HID（Human Interface Device）にて デバイスとキーを一意に指定できる数列が定義されている 0x07 はキーボードを意味する 2026/2/5 ryu(@ryu_trifolium) 12

• https://www.usb.org/document-library/hid-usage-tables-17

Nix 日本語コミュニティゼミ 0x7000000E3 後半の数列の意味 HID（Human Interface Device）にて デバイスとキーを一意に指定できる数列が定義されている 0xE3 は Keyboard Left GUI（Command キー）を意味する 2026/2/5 ryu(@ryu_trifolium) 13

Nix 日本語コミュニティゼミ 0x7000000E3 この値の意味 前半がデバイスの種類 後半がキーの種類 組み合わせると、キーボードの Command キーという意味になる 0x07000 = Keyboard 0x000E3 = Left GUI Key -> 0x07000000E3 -> 0x7000000E3 2026/2/5 ryu(@ryu_trifolium) 14

Nix 日本語コミュニティゼミ system.keyboard.userKeyMapping 30064771299 = 0x7000000E3 = Keyboard Left GUI 30064771298 = 0x7000000E2 = Keyboard Left Alt Command を Alt に変えるという設定と合致している (mkIf cfg.swapLeftCommandAndLeftAlt { HIDKeyboardModifierMappingSrc = 30064771299; HIDKeyboardModifierMappingDst = 30064771298; }) 2026/2/5 ryu(@ryu_trifolium) 15

Nix 日本語コミュニティゼミ configuration.nix での使い方 system.keyboard = { enableKeyMapping = true; userKeyMapping = [ # Command -> Alt {HIDKeyboardModifierMappingSrc = 30064771299; HIDKeyboardModifierMappingDst = 30064771298;} # Alt -> Command {HIDKeyboardModifierMappingSrc = 30064771298; HIDKeyboardModifierMappingDst = 30064771299;} ]; この設定と同じ結果になる # # swapLeftCommandAndLeftAlt = true; }; 2026/2/5 ryu(@ryu_trifolium) 16

Nix 日本語コミュニティゼミ 何ができるようになったのか？ before system.keyboard.* に用意されたマッピング変更しか使えない after キーとキーの交換なら自由に設定できる サードパーティ製ツール不要（OS 標準機能） ※複雑なマッピングは不可 （単押しは Ctrl、長押しは Command、といった設定など） 2026/2/5 ryu(@ryu_trifolium) 17

Nix 日本語コミュニティゼミ 特殊なキーについて Fn（Globe）キーは Apple 独自のキー 定義が特殊（Vendor-defined） 0xFF00000003：left Fn 0xFF0100000003：right Fn 公式情報は見つからず What is the hex ID for Fn key スレッドに書かれていた値 2026/2/5 ryu(@ryu_trifolium) 18

• https://apple.stackexchange.com/questions/340607/what-is-the-hex-id-for-fn-key

Nix 日本語コミュニティゼミ 活用例 Caps Lock と Fn に変更 日本語/英語 切り替えがスムーズ & 押しやすい system.keyboard = { enableKeyMapping = true; userKeyMapping = [ { # Caps Lock -> Fn Globe HIDKeyboardModifierMappingSrc = 30064771129; # Caps Lock HIDKeyboardModifierMappingDst = 1095216660483; # Fn Globe } ]; }; キー （ ）キー （ 2026/2/5 ryu(@ryu_trifolium) キー ）キー 19

Nix 日本語コミュニティゼミ

自作関数で可読性を確保する
userKeyMapping =
let
mkKeyMapping =
let
hexToInt = s: pkgs.lib.trivial.fromHexString s;
in
src: dst: {
HIDKeyboardModifierMappingSrc = hexToInt src;
HIDKeyboardModifierMappingDst = hexToInt dst;
};
capsLock = "0x700000039";
fnKey = "0xFF00000003";
in
[
# Caps Lock -> Fn
(mkKeyMapping capsLock fnKey)
];

2026/2/5 ryu(@ryu_trifolium)

20

Nix 日本語コミュニティゼミ 自分の設定 Windows ライクなマッピングにしています leftControl = "0x7000000E0"; leftCommand = "0x7000000E3"; capsLock = "0x700000039"; fnKey = "0xFF00000003"; in [ # Left Control <-> GUI(Command) (mkKeyMapping leftControl leftCommand) (mkKeyMapping leftCommand leftControl) # Caps Lock -> Fn (mkKeyMapping capsLock fnKey) ]; 2026/2/5 ryu(@ryu_trifolium) 21

Nix 日本語コミュニティゼミ 詳細は記事にまとめています https://zenn.dev/trifolium/articles/a6fc32a05be6d0 2026/2/5 ryu(@ryu_trifolium) 22

• https://zenn.dev/trifolium/articles/a6fc32a05be6d0

Nix 日本語コミュニティゼミ 今日話さなかったこと なぜ によるマッピング設定が再起動でも失われないのか による変更は再起動でリセットされる hidutil hidutil 答えの頭出し nix-darwin の にて 様々な設定を行うシェルスクリプトが定義されている nix-darwin が に を配置している 再起動時に設定用シェルスクリプトが自動実行される 2026/2/5 ryu(@ryu_trifolium) system.activationScripts /Library/LaunchDaemons org.nixos.activate-system.plist 23

Nix 日本語コミュニティゼミ 注意 は となっています おそらく、公式の意図は「内部利用の関数扱い」だと思われます （＝ユーザーが直接利用しない想定） 利用は自己責任でお願いいたします system.keyboard.userKeyMapping 2026/2/5 ryu(@ryu_trifolium) internal = true; 24

Nix 日本語コミュニティゼミ ご清聴ありがとうございました 2026/2/5 ryu(@ryu_trifolium) 25