{"id":13862609,"url":"https://github.com/veehaitch/macos-remap-keys","last_synced_at":"2025-07-29T05:05:57.111Z","repository":{"id":186407828,"uuid":"336833295","full_name":"veehaitch/macos-remap-keys","owner":"veehaitch","description":"Remap keys with pure macOS functionality.","archived":false,"fork":false,"pushed_at":"2023-10-03T21:49:53.000Z","size":20,"stargazers_count":16,"open_issues_count":1,"forks_count":2,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-18T15:54:24.071Z","etag":null,"topics":["keyboard","macos","remap"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/veehaitch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-02-07T16:28:34.000Z","updated_at":"2024-11-15T16:24:14.000Z","dependencies_parsed_at":null,"dependency_job_id":"54ebe591-5706-472d-bac1-bccd16e3876e","html_url":"https://github.com/veehaitch/macos-remap-keys","commit_stats":null,"previous_names":["veehaitch/macos-remap-keys"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veehaitch%2Fmacos-remap-keys","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veehaitch%2Fmacos-remap-keys/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veehaitch%2Fmacos-remap-keys/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veehaitch%2Fmacos-remap-keys/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/veehaitch","download_url":"https://codeload.github.com/veehaitch/macos-remap-keys/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245040235,"owners_count":20551297,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["keyboard","macos","remap"],"created_at":"2024-08-05T06:01:48.502Z","updated_at":"2025-03-23T00:32:33.415Z","avatar_url":"https://github.com/veehaitch.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Remap macOS Keys\n\nRemap keys with pure macOS functionality.\n\nAlthough the efforts of the [Karabiner-Elements](https://github.com/pqrs-org/Karabiner-Elements)\nproject are highly appreciated, using it always felt too intrusive and, recently,\nalso [like a liability](https://github.com/pqrs-org/Karabiner-Elements/issues/2607).\nIn fact, although quite unknown, if it comes to simple key remapping tasks,\none can use features built directly into macOS.\n\nThis project helps in defining remappings easily through a straight-forward configuration file.\n\n## Getting started\n\nClone this repository and make sure you have Python with `pyyaml` installed.\n\nEdit [`config.yaml`](config.yaml) to your needs.\nIt has the following structure:\n\n```yaml\nkeyboard:\n  fromKey1: toKey1\n  fromKey2: toKey2\n  # ...\nkeypad:\n  fromKey1: toKey1\n  # ...\n```\n\nThe `fromKey` and the `toKey` label names correspond to `.keyboard` and `.keypad`\nas defined in [`keytables.yaml`](./keytables.yaml).\n\nFor example, to remap\n\u003ckbd\u003eCaps lock\u003c/kbd\u003e to \u003ckbd\u003eBackspace\u003c/kbd\u003e, and\n\u003ckbd\u003eBackspace\u003c/kbd\u003e to \u003ckbd\u003eDelete\u003c/kbd\u003e\nyou have to define `config.yaml` as follows:\n\n```yaml\nkeyboard:\n  Capslock: Backspace\n  Backspace: Delete\n```\n\nApply your configuration as follows:\n\n```bash\nhidutil property --set `./remap.py --hidutil-property`\n```\n\n## Persistent configuration\n\nTo keep your remapping configuration in effect across restarts,\nyou can load it automatically using launchd. To load your configuration\nautomatically on the next restart, execute the following command:\n\n```bash\n./remap.py --launchd-plist ~/Library/LaunchAgents/ch.veehait.macos-remap-keys.plist\n```\n\n## Nix?\n\nIf you're using Nix with Home Manager on Darwin, you can use something like\nthe following to manage your mappings. It takes care of applying your remapping\nconfiguration after a `home-manager switch` and also links the launchd plist \nto get picked up on restarts.\n\n```nix\n{ config, pkgs, lib, ... }:\nlet\n  macos-remap-keys-flake = builtins.getFlake \"github:veehaitch/macos-remap-keys\";\n  macos-remap-keys = macos-remap-keys-flake.defaultPackage.x86_64-darwin;\n  keytables = builtins.toPath \"${macos-remap-keys-flake}/keytables.yaml\";\n  config = pkgs.writeText \"macos-remap-config.yaml\" (builtins.toJSON {\n    keyboard = {\n      Capslock = \"Backspace\";\n      Backspace = \"Delete\";\n    };\n  });\n  macos-remap-launchd = pkgs.runCommand \"macos-remap-launchd\" { } ''\n    mkdir -p $out\n    ${macos-remap-keys}/bin/remap.py \\\n      --config \"${config}\" \\\n      --keytables \"${keytables}\" \\\n      --launchd-plist \\\n      \"$out/ch.veehait.macos-remap-keys.plist\" \u003e/dev/null\n  '';\nin\n{\n  # Activate the remappings on switch\n  home.activation.\"macosRemapKeys\" = lib.hm.dag.entryAfter [\"writeBoundary\"] ''\n    $DRY_RUN_CMD hidutil property --set \\\n      `${macos-remap-keys}/bin/remap.py \\\n      --config ${config} \\\n      --keytables ${keytables} \\\n      --hidutil-property` \u003e/dev/null\n  '';\n\n  # Activate the remappings on boot\n  home.file.\"Library/LaunchAgents/ch.veehait.macos-remap-keys.plist\".source = \"${macos-remap-launchd}/ch.veehait.macos-remap-keys.plist\";\n}\n```\n\n## Gruselkabinett\n\nAlthough very similar, the format demanded by `hidutil` isn't JSON.\nFor `hidutil property --set` to work, the values of `HIDKeyboardModifierMapping{Src,Dst}`\nhave to be numbers in their hexadecimal representation. Using a decimal representation,\nas supported by JSON, won't work.\nThat's a weird decision—just Apple things—which demands some Regex string manipulation.\n\nWonder what would happen if you'd just use a hex string instead of a number?\nmacOS crashes—completely. Hard to believe?\nGo ahead and try it yourself but make sure you don't have any unsaved work:\n\n```bash\nhidutil property --set '{\"UserKeyMapping\":[{\"HIDKeyboardModifierMappingSrc\":\"0x700000039\",\"HIDKeyboardModifierMappingDst\":\"0x70000002A\"}]}'\n```\n\n## References / Similar Articles and Projects\n\n- https://developer.apple.com/library/archive/technotes/tn2450/_index.html\n- https://dchakarov.com/blog/macbook-remap-keys/\n- https://blog.codefront.net/2020/06/24/remapping-keys-on-macos\n- https://github.com/amarsyla/hidutil-key-remapping-generator\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fveehaitch%2Fmacos-remap-keys","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fveehaitch%2Fmacos-remap-keys","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fveehaitch%2Fmacos-remap-keys/lists"}