Fcitx5: a C++ input method framework that ships only the keyboard layout engine

What Fcitx5 solves, and who is actually supposed to install it

Typing Chinese, Japanese, Korean or Vietnamese on Linux means running a process that watches keystrokes, decides when a composition starts, shows a candidate window, and hands the committed text back to whichever application has focus. Fcitx5 is that process. The README describes it as "a generic input method framework released under LGPL-2.1+", and the word framework is doing real work. The repository you are looking at is the framework, not a finished IME.

The README is blunt about this: "The main package (this repository) only contains keyboard layout engine. Coressponding input method engines need to be installed to support other languages (e.g. Chinese/Japanese/Korean)." That sentence is the single most important thing to understand before installing. Someone who clones fcitx5, builds it, and starts typing will get keyboard layouts, not Pinyin.

The intended audience is therefore split. End users on a distribution that packages Fcitx5 get it as one dependency among several, usually pulled in by a meta-package. Engine authors and addon developers get the framework itself, plus the wiki pages "Compiling fcitx5" and "Develop a simple input method". Distribution packagers get a CMake project with a Doxyfile, a po/ directory for translations, and a REUSE.toml for licence metadata. If you are none of those, you probably want an engine package, not this repository.

How the framework is laid out: engines, addons and the frontend split

The top-level layout is the architecture. src/ holds the framework itself, data/ holds shipped data files, po/ holds translations, test/ and testing/ hold test code, and third_party/ vendors dependencies. CMakeLists.txt and cmake/ drive the build; config.h.in is generated into a configured header.

The split between framework and engine is the design decision everything else follows from. Fcitx5 owns the input context, the key event pipeline, the candidate UI, and the addon loading mechanism. An engine registers itself as an addon and answers the question "given this key event and this composition state, what should happen". That means the same framework can host Pinyin, Rime, Mozc or UniKey without any of them living in this repository. The README points to a wiki page listing input method engines, and separately links Mac and Android ports that live in their own repositories under fcitx-contrib and fcitx5-android.

The platform story is narrower than "cross-platform" suggests. The README's supported-platform section says X11/Wayland, and the Wayland path is the one that has historically forced the most work, because Wayland compositors handle input differently from X11. For TTY use the README directs readers to fcitx5-fbterm or fcitx5-tmux and states that "not all features are supported". That is a real boundary, not a footnote.

Translations follow an unusual rule worth knowing before you send a patch. The README says translation happens on Transifex, that pull requests for translation updates should not be sent, and that Transifex output is pushed to the git repository nightly but not the other way round. A translation change made directly in git will be overwritten.

Installing Fcitx5 and getting a first composition on screen

The README does not give a build recipe. It gives pointers: source code releases at download.fcitx-im.org/fcitx5/, an "Install on Linux" wiki page, and a separate "Compiling fcitx5" page for developers. So the honest first step is to read the wiki page for your distribution rather than copy a command from here. Distribution packages are the normal path, and the README links a Repology badge showing packaging status across repositories.

If you are building from source, the repository is a CMake project, and the wiki page "Compiling fcitx5" is where the actual dependency list lives. The README does not spell out the build commands, so the wiki page is the place to get them.

Once the framework is installed, it still has no Chinese or Japanese engine. Installing an engine is a separate package operation specific to your distribution, and the README's Input method engines wiki page is the index to consult. What you should see after that is a tray or panel indicator for Fcitx5 and, once an engine is selected, a candidate window when you start composing. If nothing appears, the README's own bug-reporting guidance applies: report it at github.com/fcitx/fcitx5/issues, and note that the maintainers may move it to another repository if the fault turns out to be in an engine or addon rather than the framework.

Where Fcitx5 is the wrong choice, and what the README admits

The TTY case is the clearest one. The README states that for using an input method under TTY you should look at fcitx5-fbterm or fcitx5-tmux, and that not all features are supported through those routes. If your workflow is a console-only server or a rescue shell, Fcitx5 is not the tool, and the README says so rather than papering over it.

The second limitation is the engine boundary itself. Because this repository contains only the keyboard layout engine, a bug in Pinyin candidate ordering, in Rime schema handling, or in Mozc's conversion is not a bug in this repository. The README anticipates the confusion: "You can always report any fcitx 5 issue here, it might be transfer to other repos later." That is a reasonable triage policy, but it means a user's mental model of "Fcitx5 is broken" often maps to a different project's issue tracker.

The third is packaging. The README links a Repology badge rather than promising availability, which is the correct posture: whether Fcitx5 works on your machine depends on whether your distribution ships the framework and your chosen engine for your release. The README does not document rollback, nor does it document what happens when an engine is removed while the framework is running. Treat those as unverified.

Finally, registration on the project wiki requires explicit approval because of spam, and the README asks you to email the mailing list if you are not approved. That is a friction point for anyone who wants to fix documentation rather than read it.

Fcitx5 versus IBus: two different answers to the same problem

The comparison people actually search for is Fcitx5 against IBus, and the difference is architectural rather than cosmetic. IBus was designed around D-Bus as the transport between applications and the input method engine; the input method is a D-Bus service and clients talk to it over that bus. Fcitx5 is a framework with an addon system, where engines and addons load into the framework process and the framework owns the input context directly. The practical consequence is that Fcitx5's engine ecosystem is a set of addons rather than a set of D-Bus services, which is why the README can point at a wiki list of engines and at separate Mac and Android ports that reuse the same framework code.

For a user, the observable difference is in configuration surface and in how the candidate window and layout switching behave. Both projects cover X11 and Wayland, and both need engine packages for CJK input. The choice usually comes down to what your distribution configures by default and which engine you need. If your engine of choice exists as an IBus engine and not as an Fcitx5 addon, the architecture argument does not help you.

A second alternative worth naming is not a competing framework at all: it is using your desktop environment's built-in input handling. That works for simple layout switching and fails the moment you need a composition buffer with candidates. The line between those two cases is exactly the line between a keyboard layout engine and an input method engine, which is the distinction this repository is built around.

Maintenance, release cadence and the licence question

The repository is not archived, and the last push to master was on 2026-09-27. The most recent tagged release in the list is 5.1.12 on 2025-01-23, with 5.1.11 the same day and 5.1.10 on 2024-06-13. That pattern, a burst of patch releases followed by a long gap before the next one, is worth reading carefully. Master moves; tagged releases arrive less often. If you package Fcitx5 for a distribution, that gap is the thing to plan around, because a fix merged to master may sit untagged for months.

The upgrade cost is mostly the engine boundary again. Upgrading the framework does not upgrade your engines, and upgrading an engine does not upgrade the framework. A distribution that bumps the framework without rebuilding engines against it is the scenario to watch, though the README does not document an ABI or plugin compatibility policy, so that risk cannot be confirmed from what the project publishes.

On licensing, the README states Fcitx5 is released under LGPL-2.1+. The repository carries a LICENSES/ directory and a REUSE.toml, which is the machine-readable form of per-file licence metadata used by the REUSE tooling. LGPL-2.1+ is a copyleft licence with a linking exception for the library case, and it differs from a permissive licence in ways that matter if you redistribute a modified framework. That is a statement about what the licence is, not advice about your situation; read the licence text in LICENSES/ and talk to someone qualified if you are shipping a modified build.

Editorial conclusion

Adopt Fcitx5 if you run X11 or Wayland on Linux or BSD and you want an input method framework whose main package stays narrow while engines and addons plug in separately. Do not adopt it if you need IME behaviour inside a bare TTY: the README points to fcitx5-fbterm or fcitx5-tmux and warns that not all features are supported there. Do not adopt it expecting a working Chinese, Japanese or Korean IME out of the box either, because the main package contains only the keyboard layout engine. Before you commit, read the Install Fcitx 5 wiki page for your distribution and check the Input method engines list for the engine you actually need, then confirm that engine is packaged for your release. The release cadence tells its own story: 5.1.12 landed on 2025-01-23, and the last push to master was on 2026-09-27.

Frequently asked questions

Official sources

1. fcitx/fcitx5 on GitHub
2. Issues
3. Project website
4. README
5. Releases