Fcitx5 macOS

June 2, 2026 · View on GitHub

English | 中文

Fcitx5 macOS

Fcitx5 input method framework ported to macOS ≥ 13.3.

Please download installer and read documentation.

Plugins

Fcitx5 only packages keyboard engine. To install other engines or tables, use the built-in Plugin Manager.

Build

Native and cross build on macOS ≥ 26.2 is supported.

This is NOT an Xcode project, but Xcode ≥ 26.4 is needed for Swift 6.3 compiler.

Install dependencies

You may use nvm to install node, then

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
brew install cmake ninja extra-cmake-modules gettext librsvg
./scripts/install-deps.sh
npm i -g pnpm
pnpm --prefix=fcitx5-webview i

Build with CMake

./scripts/patch.sh
cmake -B build/$(uname -m) -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build/$(uname -m)
sudo cmake --install build/$(uname -m)

After the first time you execute cmake --install, you need to logout and login, then add Fcitx5 in System Setttings -> Keyboard -> Input Sources, Chinese Simplified.

For installations afterwards, clicking Restart in Fcitx5 menu suffices.

You can also use Cmd+Shift+B in VSCode to execute a task.

Code sign

Some features (e.g. notifications, core dump) require the app bundle be code-signed after installation:

./scripts/code-sign.sh

Debug

Console.app

  • Check Include Info Messages and Include Debug Messages in Action menu.
  • Put FcitxLog in Search.

Log

/tmp/Fcitx5.log contains all log in Console.app, plus those written to stderr by engines, e.g. rime.

lldb

SSH into the mac from another device, then

$ /usr/bin/lldb
(lldb) process attach --name Fcitx5

Core dump

sudo chmod 1777 /cores
sudo sysctl kern.coredump=1
ulimit -c unlimited  # only works for current shell
pkill Fcitx5; /Library/Input\ Methods/Fcitx5.app/Contents/MacOS/Fcitx5

When Fcitx5 crashes, it creates a ~10GB core file under /cores.

/usr/bin/lldb -c /cores/core.XXXX
(lldb) bt

Test

Unit test

ctest --test-dir build/$(uname -m) --output-on-failure

E2E test

npm i -g appium
appium driver install mac2
pip install -r appium/requirements.txt
pytest appium

Use /Applications/Xcode.app/Contents/Applications/Accessibility Inspector.app to check identifier of UI elements.

Translation

Swift sources

To update .strings files for each supported locale, run

cmake --build build/$(uname -m) --target GenerateStrings

This will, e.g., update assets/zh-Hans/Localizable.strings, and then the translator can work on it.

C++ sources

First, create assets/po/base.pot file:

cmake --build build/$(uname -m) --target pot

To add a new language, do

cd po && msginit -l <locale>

Then, use a PO file editor to translate strings.

Finally, to merge new strings into PO files, do

cd po && msgmerge -U <locale>.po base.pot

Credits