parallels-layout-sync

Sync keyboard layouts between macOS and a Linux VM in Parallels Desktop — exactly 1:1, including custom Mac layouts.

По-русски — ниже.

The problem

Parallels Desktop synchronizes keyboard layouts with Windows guests only (KB125490). A Linux guest (Kali, Ubuntu, …) keeps its own xkb layout, so you end up switching the layout twice — once on the Mac, once in the VM.

Worse: even if you sync the switching, the layouts themselves don't match. Stock xkb layouts are not the macOS layouts:

• macOS Russian – Phonetic (мнемоническая) ≠ xkb ru(phonetic) — different letters on different keys (q is я on a Mac, not so in xkb);
• third-party Mac layouts (e.g. RussianWin) have no xkb equivalent at all;
• Option-level symbols (€ ≤ ≥ « » …) differ everywhere.

So you type in the VM and get characters you didn't press.

The solution

Two parts:

1. kbdsync — a tiny LaunchAgent on macOS. It watches the active macOS input source and instantly loads the matching keymap inside the Linux guest via prlctl exec … xkbcomp. It also re-pushes every 60 s, so the guest converges even after a VM reboot. Switch the layout on the Mac — the VM follows.
2. dump_kbd + gen_xkb — a layout cloner. dump_kbd reads your actual macOS layouts key-by-key through UCKeyTranslate (base / Shift / Option / Shift+Option, dead keys included) and gen_xkb.py turns that dump into xkb keymaps that reproduce the Mac layout exactly — the same physical key produces the same character in the VM as on the Mac.

 macOS input source change
        │  (DistributedNotificationCenter)
        ▼
   kbdsync (LaunchAgent)
        │  prlctl exec <VM> 'xkbcomp …/keymaps/mac_ruwin.xkb $DISPLAY'
        ▼
 Linux guest X server — keymap is a 1:1 clone of the Mac layout

Requirements

• macOS with Parallels Desktop (built/tested with PD 20)
• Linux guest with Parallels Tools installed and an X11 session (Xfce etc.; Wayland is not supported)
• Xcode Command Line Tools on the Mac (swiftc, clang)

Install

git clone https://github.com/alshfu/parallels-layout-sync.git
cd parallels-layout-sync

# 1. configure: VM name + your layouts
mkdir -p ~/.config/kbdsync
cp macos/config.example.json ~/.config/kbdsync/config.json
$EDITOR ~/.config/kbdsync/config.json

# 2. build & start the watcher
./install.sh

# 3. generate exact clones of your Mac layouts and copy them into the VM
~/.local/kbdsync/dump_kbd "RussianWin" "Swedish-Pro" > /tmp/mac_layouts.json
python3 ~/.local/kbdsync/gen_xkb.py /tmp/mac_layouts.json \
    --map RussianWin=mac_ruwin --map Swedish-Pro=mac_se --out /tmp/xkb_out
tar czf - -C /tmp/xkb_out . | ssh user@<vm-ip> 'mkdir -p ~/.xkb && tar xzf - -C ~/.xkb'

The suffix values in config.json are matched against the macOS input source ID (com.apple.keylayout.RussianWin ends with RussianWin). keymap names must match the --map variants. fallback is a stock xkb layout used if the clone is unavailable.

Notes & limitations

• Direction is Mac → VM. That's the natural one: macOS intercepts the layout switch shortcut even while the VM window is focused.
• Guest session must be X11; the tool talks to the X server via xkbcomp.
• The keycode table targets ISO Mac keyboards (the extra <> key). ANSI keyboards work too — the ISO-only entries are simply unused.
• Don't configure a layout switcher inside the guest (Xfce keyboard plugin, grp-toggle options) — it would fight the sync.
• Pairs well with a wrong-layout fixer on the Mac side (e.g. RuSwitcher or Punto Switcher): when it auto-switches the Mac layout, the VM follows automatically.

Uninstall

launchctl bootout gui/$(id -u)/local.kbdsync
rm -rf ~/.local/kbdsync ~/.config/kbdsync ~/Library/LaunchAgents/local.kbdsync.plist
# in the guest: rm -rf ~/.xkb   (and re-set your normal layout)

License

MIT — see LICENSE.

---

По-русски

Синхронизация раскладки клавиатуры между macOS и Linux-ВМ в Parallels — 1:1, включая кастомные раскладки Mac.

Проблема

Parallels умеет синхронизировать раскладку только с Windows-гостями. В Linux-госте (Kali и т.п.) раскладка живёт своей жизнью — переключать приходится дважды. А даже если синхронизировать переключение, сами раскладки не совпадают: маковская «Русская — фонетическая» (мнемоническая) ≠ xkb ru(phonetic), у RussianWin вообще нет линуксового аналога. Печатаешь в ВМ — выходит не то.

Решение

1. kbdsync — агент на macOS: следит за раскладкой Mac и мгновенно загружает соответствующую карту в гостевой Linux через prlctl exec … xkbcomp. Раз в 60 секунд повторяет отправку — ВМ приходит в нужное состояние даже после перезагрузки.
2. dump_kbd + gen_xkb — клонировщик: снимает твои маковские раскладки поклавишно (все уровни: Shift, Option, мёртвые клавиши) и генерирует xkb-карты, которые воспроизводят Mac-раскладку точно: та же физическая клавиша → тот же символ в ВМ.

Установка

См. шаги выше — они одинаковые для всех языков. Суть:

1. cp macos/config.example.json ~/.config/kbdsync/config.json и отредактировать (имя ВМ из prlctl list, твои раскладки).
2. ./install.sh — соберёт и запустит агента.
3. Сгенерировать клоны раскладок и скопировать их в ВМ (команды выше).

Ограничения

• Направление — Mac → ВМ (переключение ловит macOS, даже когда окно ВМ в фокусе).
• В госте нужна X11-сессия (не Wayland).
• Не настраивай свой переключатель раскладки внутри гостя — будет конфликтовать.
• Отлично дополняется авто-исправителем раскладки на Mac (RuSwitcher / Punto Switcher): он переключил Mac — ВМ переключилась сама.