gen-compose – generates compose key keybindings for macos.

A compose key (sometimes called multi key) is a key on a computer keyboard that indicates that the following (usually 2 or more) keystrokes trigger the insertion of an alternate character, typically a precomposed character or a symbol.

Compose keys lets you insert complex character by entering multiple characters in a succession:

screencast demonstration of compose key

e.g. + d + o + w + n will insert 👇

Mac os doesn’t come with a compose key feature built-in. However there’s a short hack to make it work:

  1. Keys can be rebound in mac via ~/Library/KeyBindings/DefaultKeyBinding.dict dictionary file.
  2. The rebound keys can be chained like compose keys e.g. pressing abcd can be made to insert AlphaBetaCharlieDad
  3. Modifier keys cannot be rebound

With these three rules we can replicate compose key and even set it to work with a mod key!


gen-compose can be installed via python manager with py3.6+ versions:

$ pip3 install --user gen-compose
$ gen-compose --help
Usage: gen-compose [OPTIONS] [MAPPINGS]...

  Generate macos rebind file from compose json mapping

  --key TEXT  key to use as compose key  [default: §]
  -r, --raw   just keymap without prefix
  --help      Show this message and exit.


  1. First lets fix modifier key issue by forcing modifier to be a character. For example to use right_options key we need to use karabiner elements and remap it to some unused key like non_us_backslash:
    karabiner compose screenshot

  2. Now we have the compose key ready: if we click right_options it should insert § character

    However we cannot compose anything yet as we have no compose mappings yet. For that we need to modify keybindings dictionary located in ~/Library/KeyBindings/DefaultKeyBinding.dict.

    It’s written in some cryptic hard to edit format and here’s where gen-compose comes in and lets you write yaml files instead!


  1. Create yaml mappings file (e.g. mappings/readme.yaml):
    cat: "(^≗ω≗^)"
    "+1": 👍
    "-1": 👍
    ":(": "my face is sad"

    This map defines key combinations and texts that will be inserted, e.g. will insert thumbs up.

    note: see mappings directory for some built in mappings

  2. Using gen-compose we generated .dict keybind file file from our yaml configuration:
    $ gen-compose mappings/readme.yaml
    {"§" = {
      "c" = {
        "a" = {
          "t" = ("insertText: ", "(^≗ω≗^)");
      "+" = {
        "1" = ("insertText: ", "👍");
      "-" = {
        "1" = ("insertText: ", "👍");
      ": " = {
        "(" = ("insertText: ", "my face is sad");

    note: multiple mappings can be used to generate a single keymap: $ gen-compose map1.yaml map2.yaml

  3. Now save it directly to keybinds file:
    $ gen-compose mappings/readme.yaml > ~/Library/KeyBindings/DefaultKeyBinding.dict
  4. Restart your programs and type §+1 and you’ll see 👍!
  5. Customize your own mapping or see /mappings for some existing configurations and have fun!

note: Some programs need a hard reboot to take in the map, like kill -9 sort of reboot to start working.

Notes and Issues

  • There’s no way to really debug this other than trial and error and making sure applications are restarted after every update.
  • When multiple keymaps (eg compose-gen map1.yaml map2.yal) provided they will be joined and updated in order they are provided.
  • Keymap does not allow completely overlapping keys. e.g. egg and eggplant will break because it’s impossible to map two overlapping values as keymap functionality has no timeout (i.e. break if nothing is typed after a second and insert egg, instead it will wait indefinitely for you to finish eggplant)

    If overlap happens compose-gen will choose the shorter form and discard the long one.

    To fix this add end terminator character such as space: egg rather than egg in your mappings.
  • DefaultKeyBinding.dict map doesn’t work in some popular programs:

Related Resources

Read More

ترك الرد

من فضلك ادخل تعليقك
من فضلك ادخل اسمك هنا