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]. https://www.bilibili.com/video/BV13ji2YLE3m.

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:

# 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):

# 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:

$ mkdir -p ~/.config/autostart/

Set Fcitx 5 to start on boot:

$ 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:

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:

$ 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):

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:

# pkg install zh-fcitx5-rime zh-rime-essay

• Or install using Ports:

# 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]. https://learn.microsoft.com/en-us/windows/win32/tsf/text-services-framework. 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]. https://fcitx-im.org/wiki/History/. 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]. https://fcitx-im.org/wiki/Using_Fcitx_5_on_Wayland. 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:

$ 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.