FontBookSync

Current version / 当前版本: v0.1.0

FontBookSync is a local-first font family sync tool for macOS and Windows. It keeps licensed user-installed fonts aligned across Mac-Mac, Win-Win, and Win-Mac setups through one shared vault folder.

FontBookSync 是一个面向 macOS 和 Windows 的本地优先字体家族同步工具。它通过一个共享字体库，让多台 Mac 或 Windows 设备自动保持已授权安装字体的一致。

Use this only for fonts you are licensed to install on every synced device. The tool copies font files you already have access to; it does not bypass font licensing, DRM, activation systems, or cloud font services.

How It Works

Each device runs font_book_sync.py and points to the same vault directory. That vault can be inside Google Drive, OneDrive, iCloud Drive, Dropbox, Syncthing, an SMB/NAS folder, or an external drive.

On every sync cycle the tool:

1. Scans this machine's user font folder.
2. Extracts font family names from the font's OpenType/TrueType name table.
3. Copies new font files into vault/blobs.
4. Updates vault/index.json.
5. Installs missing vault fonts into this machine's user font folder.

Deletion is intentionally not synced. Removing fonts automatically across machines is risky for design projects, so the first version is add-only.

Platform Defaults

macOS:

• Publishes from ~/Library/Fonts
• Installs to ~/Library/Fonts
• Checks installed fonts in ~/Library/Fonts, /Library/Fonts, and /System/Library/Fonts

Windows:

• Publishes from %LOCALAPPDATA%\Microsoft\Windows\Fonts
• Installs to %LOCALAPPDATA%\Microsoft\Windows\Fonts
• Checks installed fonts in the user font folder and C:\Windows\Fonts
• Updates the current-user font registry and broadcasts WM_FONTCHANGE

Quick Start

Create a shared vault on the first machine:

python3 Tools/FontBookSync/font_book_sync.py init \
  --vault "$HOME/FontFamilyVault" \
  --config-out "$HOME/fontbooksync.json"

Run one sync:

python3 Tools/FontBookSync/font_book_sync.py once \
  --config "$HOME/fontbooksync.json"

Run continuously:

python3 Tools/FontBookSync/font_book_sync.py watch \
  --config "$HOME/fontbooksync.json"

On the second machine, point the config to the same shared vault folder and run the same watch command.

Windows PowerShell example:

py .\Tools\FontBookSync\font_book_sync.py once --config "$HOME\fontbooksync.json"

Status Check

Compare this device with the vault:

python3 Tools/FontBookSync/font_book_sync.py status \
  --config "$HOME/fontbooksync.json"

Important fields:

• vault_files: font files known to the shared vault.
• vault_families: font families known to the shared vault.
• installed_vault_files_here: vault files already present on this device.
• missing_vault_files_here: vault files not present on this device.
• missing_families_here: entire families missing from this device.
• partial_families_here: families where this device has only part of the set.

Config

Copy config.example.json and edit the paths:

{
  "vault": "~/FontFamilyVault",
  "device_id": "my-macbook",
  "device_name": "Red MacBook",
  "interval_seconds": 30,
  "publish_roots": ["~/Library/Fonts"],
  "installed_roots": ["~/Library/Fonts", "/Library/Fonts", "/System/Library/Fonts"],
  "install_root": "~/Library/Fonts",
  "ignore_patterns": [".*", "__MACOSX", "*.download", "*.tmp", "*.bak"],
  "refresh_font_cache": false
}

For Windows, use paths such as:

{
  "vault": "D:/FontFamilyVault",
  "publish_roots": ["%LOCALAPPDATA%/Microsoft/Windows/Fonts"],
  "installed_roots": [
    "%LOCALAPPDATA%/Microsoft/Windows/Fonts",
    "%WINDIR%/Fonts"
  ],
  "install_root": "%LOCALAPPDATA%/Microsoft/Windows/Fonts"
}

Background Use

macOS LaunchAgent command:

python3 /path/to/Tools/FontBookSync/font_book_sync.py watch \
  --config "$HOME/fontbooksync.json"

Or install the included LaunchAgent:

bash Tools/FontBookSync/mac/install-launch-agent.sh "$HOME/fontbooksync.json"

Windows Task Scheduler action:

py C:\path\to\Tools\FontBookSync\font_book_sync.py watch --config "$HOME\fontbooksync.json"

Or install the included current-user task:

powershell -ExecutionPolicy Bypass -File .\Tools\FontBookSync\windows\install-startup-task.ps1 -ConfigPath "$HOME\fontbooksync.json"

Run it at login on every synced machine. Apps that were already open may need a restart to pick up newly installed fonts.

Notes

• The sync key is the font file SHA-256 hash, so duplicate files are not copied twice.
• Family matching is derived from internal font metadata, not just file names.
• Variable fonts and font collections are handled as font files; their family names are still read from the name table when available.
• Adobe Fonts and other subscription/cloud font services may store fonts outside normal user font folders or prevent copying; those are not targeted by this tool.