> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/ask/flat/chapter-12-localization-and-input-methods/di-12.3-jie-fcitx-shu-ru-fa-kuang-jia.md). # 12.3 Fcitx Input Method Framework The input method framework and specific input methods are two different technical layers; input methods rely on the support of the framework to function. Fcitx stands for "Free Chinese Input Toy for X" (a free Chinese input toy for the X Window System). Starting from Fcitx 4, this abbreviation no longer corresponds to a single full name; the official documentation provides multiple interpretations (such as "Flexible Context-aware Input Tool with eXtension", etc.), reflecting that Fcitx's development has transcended the scope of Chinese input. > **Tip** > > For a video tutorial, see Chinese FreeBSD Community (CFC). 006-FreeBSD 14.2 Installing fcitx5 and its input methods\[EB/OL]. \[2026-04-04]. . > **Note** > > Unpredictable issues may occur on FreeBSD-CURRENT: Fcitx 5 diagnostic information displays garbled English characters, input methods exhibit abnormal Chinese character display, and input methods cannot load properly in Qt environments. ## Installing Fcitx5 * Install using pkg: ```sh # pkg install fcitx5 fcitx5-qt5 fcitx5-qt6 fcitx5-gtk2 fcitx5-gtk3 fcitx5-gtk4 fcitx5-configtool zh-fcitx5-chinese-addons ``` * Or install using Ports (`fcitx5-qt` and `fcitx5-gtk` are Ports with FLAVORs; each build only targets the corresponding Qt or GTK major version; specify FLAVOR separately as needed): ```sh # cd /usr/ports/textproc/fcitx5/ && make install clean # Main program # cd /usr/ports/textproc/fcitx5-qt/ && make FLAVOR=qt5 install clean # Qt 5 support # cd /usr/ports/textproc/fcitx5-qt/ && make FLAVOR=qt6 install clean # Qt 6 support # cd /usr/ports/textproc/fcitx5-gtk/ && make FLAVOR=gtk2 install clean # GTK 2 support # cd /usr/ports/textproc/fcitx5-gtk/ && make FLAVOR=gtk3 install clean # GTK 3 support # cd /usr/ports/textproc/fcitx5-gtk/ && make FLAVOR=gtk4 install clean # GTK 4 support # cd /usr/ports/textproc/fcitx5-configtool/ && make install clean # Graphical configuration tool for fcitx5 (based on Qt 6/KF 6) # cd /usr/ports/chinese/fcitx5-chinese-addons/ && make install clean # Input methods ``` When using the SLiM display manager, the system may prompt that IBus cannot be found. ### Fcitx 5 Auto-start on Boot After installation, configure Fcitx 5 to start automatically with the system. Create the autostart path. If configuring for another user, execute the command in that user's terminal: ```sh $ mkdir -p ~/.config/autostart/ ``` Set Fcitx 5 to start on boot: ```sh $ cp /usr/local/share/applications/org.fcitx.Fcitx5.desktop ~/.config/autostart/ ``` ## Configuring Environment Variables After completing the autostart setup, corresponding environment variables must also be configured to ensure the input method framework works properly in various applications. There are two methods to achieve this. ### X11 To set variables for Simplified Chinese UTF-8 encoding, edit the **\~/.login\_conf** file and add the following content: ```ini me:\ :lang=zh_CN.UTF-8:\ :setenv=LC_ALL=zh_CN.UTF-8,GTK_IM_MODULE=fcitx,QT_IM_MODULE=fcitx,XMODIFIERS="@im=fcitx":\ :charset=UTF-8: ``` After editing, execute the following command to update the login capability database: ```sh $ cap_mkdb ~/.login_conf ``` ### Wayland Under Wayland, the `QT_IM_MODULE` setting depends on the desktop environment: under KDE Plasma, it should be unset (Qt communicates with Fcitx 5 through KWin's `text-input` protocol); under other desktop environments, it still needs to be set to `fcitx`. Under Wayland, the `GTK_IM_MODULE` setting depends on the situation. Wayland provides input method-related protocols (`text-input` and `input-method`). GTK 3/4 can use the `text-input-v3` protocol to communicate with Fcitx 5 under Wayland without relying on the GTK input method module. If `GTK_IM_MODULE=fcitx` is set, GTK 3/4 applications will fall back to the X11 input method module, which may cause abnormal distance between the candidate box and the cursor position. Therefore, it is not recommended to set the environment variable `GTK_IM_MODULE`. Instead, specify the input method module through GTK configuration files: * Add `gtk-im-module="fcitx"` to **\~/.gtkrc-2.0** * Add `gtk-im-module=fcitx` to the `[Settings]` section of **\~/.config/gtk-3.0/settings.ini** * Add `gtk-im-module=fcitx` to the `[Settings]` section of **\~/.config/gtk-4.0/settings.ini** For programs running under XWayland, the input method is configured by the environment variable `XMODIFIERS='@im=fcitx'`. An example **\~/.login\_conf** configuration file is as follows (using a non-KDE desktop environment as an example): ```ini me:\ :lang=zh_CN.UTF-8:\ :setenv=LC_ALL=zh_CN.UTF-8,QT_IM_MODULE=fcitx,XMODIFIERS="@im=fcitx":\ :charset=UTF-8: ``` > **Note** > > If using the KDE Plasma desktop, remove `QT_IM_MODULE=fcitx` from the `setenv` above. After editing, update the login capability database. ## Installing RIME (Zhongzhou Yun) Input Method In addition to the Chinese input method plugins included with Fcitx, the RIME (Zhongzhou Yun) input method can also be installed, which is a highly customizable input method engine. * Install using pkg: ```sh # pkg install zh-fcitx5-rime zh-rime-essay ``` * Or install using Ports: ```sh # cd /usr/ports/chinese/fcitx5-rime/ && make install clean # cd /usr/ports/chinese/rime-essay/ && make install clean ``` > **Note** > > `chinese/rime-essay` is required; it is RIME's shared vocabulary and language model. Without this Port, the RIME input method will only display garbled characters. If RIME is not automatically added to the input method list, please add it manually to complete the initialization. If the configuration does not take effect for regular users, please check whether the Shell has been configured according to the tutorial. ## References * Microsoft. TSF Manager\[EB/OL]. \[2026-04-04]. . This input method architecture relationship also exists in the Windows system; this document introduces the architecture and interface specifications of the Windows Text Services Framework. * Fcitx 5. History\[EB/OL]. \[2026-04-16]. . This page records the development history and name evolution of Fcitx from its inception to the present. * Fcitx. Using Fcitx 5 on Wayland\[EB/OL]. \[2026-06-05]. . This page provides detailed instructions for configuring environment variables for Fcitx 5 under the Wayland environment. ## Troubleshooting and Outstanding Issues If using a Qt-related desktop, please update the base system and third-party software packages first before troubleshooting. When encountering issues, first run the Fcitx5 input method diagnostic tool to check configuration and environment problems: ```sh $ fcitx5-diagnose ``` If a `bash`-related prompt appears and the diagnostic result cannot be output, please install Bash. It is normal that the Fcitx Qt 4 support module is not detected in Fcitx 5.x. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://book.bsdcn.org/ask/flat/chapter-12-localization-and-input-methods/di-12.3-jie-fcitx-shu-ru-fa-kuang-jia.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.