# azooKey on macOS: a Swift Japanese IME built around the Zenzai neural converter

> azooKey-Desktop is an alpha-stage Japanese input method for macOS 15 that ships the Zenzai neural kana-kanji converter, live conversion and optional LLM conversions. It installs from a .pkg or Homebrew, and the README states plainly that operation is not guaranteed.

**azooKey/azooKey-Desktop** — azooKey-Desktop is an open-source Japanese input method for macOS, written in Swift and powered by the Zenzai neural kana-kanji converter. It provides live conversion, optional LLM-based “Magic Conversions”, and Tuner-backed personalization for a smooth, desktop typing experience. 

- Repository: https://github.com/azooKey/azooKey-Desktop
- Stars: 1,035 · Forks: 89
- Language: Swift
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/azookey-azookey-desktop

## What azooKey on macOS is for

azooKey on macOS is an open-source Japanese input system for macOS, written in Swift and distributed under the MIT licence. The README describes it as the macOS edition of azooKey, and its distinguishing component is Zenzai, a neural kana-kanji conversion engine. Around that engine the project lists profile prompts, history learning, a user dictionary, live conversion, native AZIK support, and integration with a separate personalization system called Tuner. There is also an optional feature the README calls 'Magic Conversions' (いい感じ変換), driven by an LLM.

The audience is narrow and specific: people who type Japanese on a Mac and want to try a converter that is not the one Apple ships. It is not a general text-expansion tool, and it is not a cross-platform input framework. The README opens with a warning that the software is currently alpha and that operation cannot be guaranteed at all, which sets the expectations for everyone reading further. If you want a Japanese IME you can rely on without checking a repository, this is the wrong starting point.

## How Zenzai, live conversion and Tuner fit together

The architecture visible in the repository is a macOS input method bundle. The Xcode project is azooKeyMac.xcodeproj, the sources sit under azooKeyMac/, and the tests are split between azooKeyMacTests/ and azooKeyMacUITests/. Shared code lives in Core/, and Tools/ holds supporting utilities. The topics list InputMethodKit, which is the Apple framework for building input methods on macOS, so the app registers itself as an input source rather than running as an ordinary windowed application.

The neural side is shipped as model weights inside the repository. The .gitmodules file points at submodules, and the README names two of them under azooKeyMac/Resources/: zenz-v3.1-small-gguf, which holds the GGUF weights for the Zenzai converter, and base_n5_lm, which holds a language model in .marisa form. Because those submodules are stored through Git LFS, a clone without Git LFS leaves pointer files instead of real weights, and the README treats that as the first explanation for conversion quality that looks worse than the released build.

Personalization is partly delegated. The README lists a link with Tuner, a separate repository, and separately lists history learning and a user dictionary inside azooKey itself. So there are two layers: what the IME learns locally, and what the Tuner integration adds on top. The README does not describe the data flow between them, and it does not document rollback of learned data. Live conversion, meanwhile, is listed as a feature without an explanation of when it rewrites text versus when it waits for confirmation.

## Installing azooKey on macOS from the release package or Homebrew

The README gives two installation routes. The release route is to download a .pkg file from the Releases page and install it. The Homebrew route is shorter, and the README states that the same post-install configuration is required either way.

```bash
brew install azooKey
```

After installing by either route, the README's steps are: log out of macOS and log back in, then open System Settings, go to Keyboard, edit Input Sources, press the + button, choose Japanese, add azooKey, and finish. The input source then appears in the menu bar, and you select azooKey from the menu bar icon. Until the logout and the input-source addition are done, the IME is installed but not usable.

Upgrades through Homebrew use the corresponding command. The README notes that a restart may be necessary.

```bash
brew upgrade azooKey
```

The README states that macOS 15 is the verified environment. macOS 14 and macOS 26 are said to work, but the README explicitly says behaviour on them has not been verified. If you build from source rather than installing a release, the requirements are macOS 15 or later, Xcode 26.1 or later, Git LFS and SwiftLint, and the README warns that Xcode 26.0 may not build the project at all.

```bash
brew install git-lfs swiftlint
git lfs install
```

A source clone must be recursive, because the submodules carry the model weights. The README also gives a repair path for an existing clone whose submodules or LFS content are missing, and a size check on the GGUF file: tens of megabytes or more means the real weights, roughly 134 bytes means you still have a pointer.

## The alpha warning, signing and the limits of a source build

The most concrete limitation is stated by the project itself: it is alpha, and operation is not guaranteed. That is not boilerplate. The README documents failure modes that a user will actually meet. Building from source requires a working signing setup, because install.sh performs an archive build; contributors without an Apple Developer Program membership are told to switch to a Personal Team and to replace the repository's bundle identifiers, such as dev.ensan.inputmethod.azooKeyMac, with a prefix they own. A signing error during install.sh is attributed to exactly that step.

There is a second, quieter failure mode. If conversion quality is worse than the released build, the README's first suspect is Git LFS: the weights may never have been downloaded, leaving the GGUF file as a pointer. The README gives the pull command for the zenz-v3.1-small-gguf submodule and the file path to inspect. This is a build problem that looks like a model-quality problem, which is an unpleasant combination when you are trying to judge whether the converter is any good.

Development also expects resets. The README says you can kill the azooKey process to pick up a new build, but that you may need to remove and re-add the input source, or log out and back in. It also lists a known Xcode error about legacy build locations and packages, pointing at an external article rather than solving it in-repo. None of this is unusual for an input method, but it means the source path is a contributor workflow, not a casual install.

## Where azooKey on macOS is the wrong tool

The clearest boundary is the operating system. The README verifies macOS 15 only. If you are on macOS 14 or macOS 26 and you want a configuration the project has tested, azooKey on macOS is not that, by the project's own statement. If you need an IME with a support contract or a release cadence you can plan around, the alpha warning is a direct answer.

There is also a scope boundary that the README handles in an unusual way. Rather than claiming other platforms, it lists community forks: fcitx5-hazkey for Linux-family systems, azooKey-Windows for Windows, and azoo-key-skkserv, an SKK server implementation that includes a macOS GUI application. Those are separate projects maintained by other people. If your need is Windows or Linux Japanese input, the macOS repository is not the thing to install, and the README itself points elsewhere.

The last boundary is the LLM feature. 'Magic Conversions' depends on an external model, and the README lists it as a feature without documenting which provider, what leaves the machine, or what happens when the service is unreachable. If sending text to an external model is not acceptable in your context, treat that feature as off by default until you have read the code under azooKeyMac/.

## How azooKey on macOS differs from Apple's Japanese input and from SKK

The obvious alternative is the Japanese input source that ships with macOS. It requires no install, no logout, and no signing setup, and it is maintained by Apple. The difference in approach is the converter: azooKey on macOS runs Zenzai, a neural kana-kanji conversion engine, with model weights shipped alongside the app, and it adds live conversion plus LLM-assisted conversions. Apple's input source does not expose those knobs. The trade is control and conversion behaviour against the absence of any installation or alpha-stage risk.

A second comparison sits inside the README's own fork list. azoo-key-skkserv is an SKK server implementation, and SKK is a different model of Japanese input: the user composes in kana and confirms, rather than relying on a predictive converter to pick kanji. Someone who prefers that style is not served by Zenzai's neural conversion, and the fork exists precisely because the same engine can be exposed to an SKK client. Choosing between them is choosing an input philosophy, not comparing two builds of one program.

For personalization, the README names Tuner as a separate project rather than a component of azooKey on macOS. That matters if you want the optimization to be inspectable or reusable outside this IME. The README does not say whether Tuner can be used without azooKey, so the direction of that dependency is something to check in the Tuner repository.

## Licence, maintenance and the v1.0 roadmap

The repository is MIT licensed, with the LICENSE file at the top level. MIT is permissive: it allows use, modification and redistribution provided the copyright notice and licence text are kept. For an input method that bundles model weights, the licence file covers the code, and the README does not state the terms of the GGUF weights or the .marisa language model pulled through Git LFS. If you plan to redistribute a build, that is the first thing to verify, in the submodule repositories rather than in this README. Nothing here is legal advice.

The repository is not archived, and the last push was on 2026-09-06. The recent releases listed are v0.1.5-beta.1 on 2026-06-13, v0.1.4 on 2026-05-17, and v0.1.4-beta.2 on 2026-05-10. The version numbers, all below 1.0, match the README's own framing: it links a meta issue, '#181', as the roadmap toward a v1.0 release. That issue, not this article, is where to find what the maintainers consider unfinished.

Upgrade cost depends on the route. Homebrew users run brew upgrade azooKey, and the README warns a restart may be needed. Source users rebuild and reinstall, and may have to remove and re-add the input source or log out. Because the neural weights arrive through Git LFS submodules, a source upgrade can also change the model files, which is worth knowing before you attribute a change in conversion quality to the app code.

## Conclusion

Adopt azooKey on macOS if you type Japanese on macOS 15 and want to try the Zenzai neural converter and live conversion in a native Swift input method, accepting the README's warning that it is alpha and that behaviour is not guaranteed. Skip it if you need a supported, release-stable IME, or if you are on macOS 14 or macOS 26 and want a configuration the project has actually verified. Before installing, check the Releases page for the current .pkg, confirm whether Homebrew's azooKey formula is what you want, and read the v1.0 roadmap issue (#181) to see what the maintainers still consider unfinished.

## FAQ

### How do I install azooKey on macOS?

Download the .pkg file from the Releases page and install it, or run brew install azooKey. Either way the README then requires you to log out and back in, add azooKey under System Settings > Keyboard > Input Sources, and select it from the menu bar icon.

### Which macOS versions does azooKey on macOS support?

The README states that macOS 15 is the verified environment. It says macOS 14 and macOS 26 can also be used, but that behaviour on them has not been verified.

### Why is azooKey's conversion quality worse than the released build when I build from source?

The README points first at Git LFS: without it the Zenzai weights stay as pointer files. It gives a size check on azooKeyMac/Resources/zenz-v3.1-small-gguf/ggml-model-Q5_K_M.gguf, where tens of megabytes or more means the real weights and roughly 134 bytes means a pointer, and a git lfs pull command to fix it.

### Is azooKey on macOS stable enough for daily use?

The README states that the project is currently alpha and that operation cannot be guaranteed at all. It also documents needing to remove and re-add the input source or log out during development, so the project's own documentation does not present it as a drop-in replacement.

## Sources

- [azooKey/azooKey-Desktop on GitHub](https://github.com/azooKey/azooKey-Desktop)
- [Issues](https://github.com/azooKey/azooKey-Desktop/issues)
- [License: MIT](https://github.com/azooKey/azooKey-Desktop/blob/main/LICENSE)
- [README](https://github.com/azooKey/azooKey-Desktop/blob/main/README.md)
- [Releases](https://github.com/azooKey/azooKey-Desktop/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/azookey-azookey-desktop