Chinese IME (Fcitx)

  • Description: Chinese input methods on Ubuntu via Fcitx — install, configure Sogou/Google Pinyin/Rime, im-config, switch and customize, GNOME/KDE integration, Wayland gotchas
  • My Notion Note ID: K2B-1-5
  • Created: 2020-06-08
  • Updated: 2026-05-15
  • License: Reuse is very welcome. Please credit Yu Zhang and link back to the original on yuzhang.io

Table of Contents

1. Overview

Problem: 104-key keyboard → Latin letters. CJK → thousands of characters per script. Need a keystroke → character layer.

Two-tier solution: IMF (framework, separate process) intercepts keystrokes for participating apps; IMEs (engines) implement specific schemes (Pinyin, Bopomofo, Wubi, Cangjie, kana, hangul, etc.). Framework talks to engines.

Dominant Linux frameworks:

  • IBus — default on Ubuntu 22.04+ / Fedora; tight GNOME integration; Red Hat-maintained.
  • Fcitx5 — active Fcitx rewrite; richer third-party engine ecosystem; preferred on KDE / i3 / non-GNOME. Upstream: fcitx/fcitx5.
  • Fcitx (4) — legacy. Packaged for old Sogou Pinyin .deb compat. No upstream maintenance.

Engines worth knowing:

  • libpinyin — open-source Pinyin; used by IBus (ibus-libpinyin) and Fcitx5 (fcitx5-chinese-addons).
  • Google Pinyin — lightweight; originally Google, now community-maintained.
  • Sogou Pinyin — proprietary; largest dictionary in mainland China; .deb from sogou.com; Fcitx 4 only.
  • Rime (中州韻) — engine-agnostic platform; ships Pinyin, Bopomofo, Cangjie, Wubi, Jyutping, etc.; YAML-configurable.

Scope: Pinyin on Ubuntu.

2. Pick a Framework

Framework Best for Notes
IBus GNOME, default Ubuntu desktop Works out of the box; configured via gnome-control-center region
Fcitx5 KDE, i3, sway, third-party engines Wider engine selection; more granular config; preferred for Rime
Fcitx 4 Sogou Pinyin (legacy .deb only) Frozen upstream; use only if Sogou is a hard requirement
  • Only one framework active at a time. Switching → re-run im-config + log out.

Check active framework:

im-config -m                                   # active configuration (system + user)
im-config -l                                   # all available configurations on this machine
echo "$GTK_IM_MODULE $QT_IM_MODULE $XMODIFIERS"

3. Install Fcitx5 (Recommended)

Install framework + Chinese addons (libpinyin, Cantonese, Wubi, table input):

sudo apt install fcitx5 fcitx5-chinese-addons fcitx5-frontend-gtk3 fcitx5-frontend-gtk4 fcitx5-frontend-qt5 fcitx5-frontend-qt6

Activate → log out → log back in → launch configurator:

im-config -n fcitx5
fcitx5-configtool

Configurator: uncheck Only Show Current Language → search Pinyin (libpinyin) → right-arrow to add → keep keyboard layout (e.g. Keyboard - English (US)) on top so Ctrl+Space toggles English ↔ Pinyin.

Autostart: X11 → /etc/xdg/autostart/org.fcitx.Fcitx5.desktop. Tiling WMs → add fcitx5 -d & to WM autostart.

4. Install Fcitx4 (Legacy)

Only needed for proprietary Sogou Pinyin .deb (not rebuilt for Fcitx5).

sudo apt install fcitx fcitx-config-gtk
im-config

im-config dialog: OK → Yes → fcitx → OK.

Pinyin engine — Google from repos or Sogou from a .deb:

sudo apt install fcitx-googlepinyin
sudo apt install ./sogoupinyin_*.deb

Reboot → run GTK configurator:

fcitx-config-gtk3

Click + → uncheck Only Show Current Language → find Sogou Pinyin / Google Pinyin → OK.

Fcitx5 + Fcitx 4 packages conflict on im-config + *_IM_MODULE env vars → do not install both.

5. Pinyin Engines

5.1 libpinyin (Default)

Bundled with fcitx5-chinese-addons (no extra install). Cloud-free; learns from input; supports full-pinyin + double-pinyin (双拼). Cloud suggestions → fcitx5-configtool → Addons → Cloud Pinyin.

5.2 Google Pinyin

Lightweight, fast startup, smaller dictionary than libpinyin or Sogou.

sudo apt install fcitx5-googlepinyin    # Fcitx5
sudo apt install fcitx-googlepinyin     # Fcitx 4

5.3 Sogou Pinyin

Proprietary, largest dictionary, popular in mainland China. .deb from pinyin.sogou.com/linux. Fcitx 4 build only; Ubuntu 22.04+ → depends on libssl1.1 (removed); see Pitfalls (§10).

sudo apt install ./sogoupinyin_*.deb

5.4 Rime

Most actively maintained, fully configurable engine. Schemas: Pinyin, Bopomofo, Jyutping, Cangjie, Wubi, Stroke.

sudo apt install fcitx5-rime    # Fcitx5
sudo apt install ibus-rime      # IBus

Add Rime as input method in fcitx5-configtool. Default schema = Luna Pinyin (朙月拼音).

6. Rime Configuration

Config = YAML, priority-ordered. Directories: Fcitx5 → ~/.local/share/fcitx5/rime/; IBus → ~/.config/ibus/rime/. Redeploy after every edit — tray icon → Redeploy, or:

rime_deployer --build ~/.local/share/fcitx5/rime/

6.1 Switch Schema

F4 (while Rime active) → schema list. Or edit default.custom.yaml:

patch:
  schema_list:
    - schema: luna_pinyin_simp
    - schema: double_pinyin
    - schema: bopomofo
    - schema: wubi86

6.2 Simplified Chinese by Default

Luna Pinyin defaults → traditional. Use luna_pinyin_simp, or patch:

# ~/.local/share/fcitx5/rime/luna_pinyin.custom.yaml
patch:
  switches:
    - name: ascii_mode
      reset: 0
      states: [中文, 西文]
    - name: full_shape
      states: [半角, 全角]
    - name: simplification
      reset: 1
      states: [漢字, 汉字]

6.3 Custom Dictionary

# ~/.local/share/fcitx5/rime/luna_pinyin.custom.yaml
patch:
  translator/dictionary: luna_pinyin
  translator/user_dict: luna_pinyin

Or drop a .dict.yaml with custom phrases → rebuild with rime_deployer.

6.4 Double Pinyin

# ~/.local/share/fcitx5/rime/default.custom.yaml
patch:
  schema_list:
    - schema: double_pinyin_mspy   # Microsoft scheme
    # - schema: double_pinyin_flypy # Xiaohe (小鹤) scheme
    # - schema: double_pinyin       # Ziranma (自然码)

7. Switching IMEs

Shortcut Action
Ctrl+Space Toggle between active IME and English keyboard
Ctrl+Shift Cycle through configured IMEs
Super+Space GNOME shortcut to cycle through configured input sources (independent of Ctrl+Space; not a toggle)
Shift Temporary English (while in Pinyin)
Ctrl+; Quick-select recent phrase (Fcitx5)
F4 Rime schema selector

Rebind: Fcitx5 → fcitx5-configtool → Global Options → Trigger Input Method. IBus → gnome-control-center keyboard → Switch to next input source.

Disable GNOME Super+Space so Fcitx5 can claim it:

gsettings set org.gnome.desktop.wm.keybindings switch-input-source "[]"
gsettings set org.gnome.desktop.wm.keybindings switch-input-source-backward "[]"

8. Desktop Integration

Three toolkit modules: GTK, Qt, XIM. Each needs a matching env var → app loads Fcitx IM module instead of default.

8.1 Environment Variables

Add to ~/.xprofile (X11) or ~/.config/environment.d/im.conf (systemd, Wayland):

export GTK_IM_MODULE=fcitx
export QT_IM_MODULE=fcitx
export XMODIFIERS=@im=fcitx
export SDL_IM_MODULE=fcitx
export GLFW_IM_MODULE=ibus   # Kitty terminal etc.
  • Fcitx 4 → same values (fcitx, not fcitx5); framework reads same module name.
  • IBus → swap in ibus:
export GTK_IM_MODULE=ibus
export QT_IM_MODULE=ibus
export XMODIFIERS=@im=ibus

8.2 GNOME

IBus auto-launched as GNOME service. Add sources → Settings → Keyboard → Input Sources. Fcitx5 on GNOME → disable IBus first (im-config -n fcitx5); Fcitx5 autostart desktop file launches it.

8.3 KDE

Auto-detects Fcitx5 via kcm_keyboard. Layouts → System Settings → Input Devices → Virtual Keyboard. No manual env vars on recent KDE → systemd user service sets them.

8.4 i3 / sway / dwm

Tiling WMs don't autostart Fcitx5. Add to WM config:

# ~/.config/i3/config
exec --no-startup-id fcitx5 -d

# ~/.config/sway/config
exec fcitx5 -d

Ensure env vars set before WM starts (via ~/.xprofile or display manager session script).

9. Wayland Gotchas

CJK on Wayland: functional but rough edges remain.

9.1 Electron Apps (VSCode, Slack, Discord, Chromium)

Default → X11 (XWayland); Pinyin works via XMODIFIERS=@im=fcitx + XIM. Native Wayland + text-input-v3 (better preedit positioning) → launch with:

code --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

Or persistently:

# ~/.config/electron-flags.conf
--enable-features=UseOzonePlatform,WaylandWindowDecorations
--ozone-platform=wayland
--enable-wayland-ime

--enable-wayland-ime required on Chromium ≥ 105 for IME to work at all under native Wayland.

9.2 Qt Apps

Qt 6.7+ → native text-input-v3 on Wayland (Qt 6.8.2+ has bug fixes). Qt 5 → no text-input-v3; still needs QT_IM_MODULE=fcitx + fcitx5-frontend-qt5. For Qt 6 apps that pre-date 6.7 or compositors without text-input-v3, install fcitx5-frontend-qt6 as fallback.

9.3 GTK Apps

GTK 3 + GTK 4 → text-input-v3 natively on Wayland; do NOT need GTK_IM_MODULE=fcitx under native Wayland. Upstream Fcitx5 recommends NOT setting GTK_IM_MODULE globally — it forces the Fcitx GTK module even on native Wayland. Best: leave unset (toolkit uses text-input-v3); set only via XWayland-specific paths if needed for X11 fallback apps.

9.4 Preedit Rendering

Preedit (composing text before commit) drawn by app's toolkit. Native Wayland + text-input-v3 → inline; XWayland → floating popup near cursor. Older Electron / Firefox < 119 → broken cursor positioning → popup at screen corner.

9.5 Root Apps and Sudo

Root process (sudo gedit) cannot see user's IM service. Fix: sudo -E (inherit env), or pkexec. Graphical editing as root is generally discouraged.

10. Pitfalls

IM module mismatch. Ctrl+Space works in some apps but not others → usually wrong toolkit module. Verify:

env | grep -E 'IM_MODULE|XMODIFIERS'
fcitx5-diagnose

fcitx5-diagnose → full report on env vars, installed addons, known issues.

Sogou Pinyin on Ubuntu 22.04+. Sogou .deb depends on libssl1.1 + Fcitx 4 → both gone from current Ubuntu. Workarounds: install libssl1.1 from focal-security, or switch to libpinyin / Rime. Long-term → Sogou unmaintained on Linux.

Fcitx + IBus coexistence. Both can install simultaneously → only one can be active IM. Switch with im-config -n <framework> + log out. Leftover env vars from previous framework → silent failures.

Fcitx5 vs Fcitx 4 package conflict. Shared binary names (fcitx-config-gtk3 vs fcitx5-configtool) → wrong *_IM_MODULE value routes keystrokes to inactive framework. Pick one.

Root-owned apps don't see IM service. IM service runs as per-user systemd unit → sudo clears relevant env vars. Use sudo -E or pkexec only if necessary.

Rime changes don't take effect. Rime caches compiled schemas. After editing any .custom.yaml / .dict.yaml → redeploy via tray icon or rime_deployer --build. Missing redeploy = most common Rime support question.

Snap and Flatpak sandboxing. Snapped apps (Firefox on Ubuntu 22.04+) ship their own GTK/Qt modules. Neither fcitx nor ibus is a standalone snap interface — both route through desktop-legacy (and historically unity7); the IM socket is exposed via those. Pinyin in snap Firefox is a moving target — depends on host framework version, Wayland vs X11, and which sandbox interfaces are connected. Input failing → check snap connections firefox (look for desktop-legacy). Chromium snap → --enable-wayland-ime required (see §9.1).

GNOME Super+Space conflict. GNOME binds Super+Space → switch input sources at IBus level. Fcitx5 as framework → binding does nothing useful. Disable via gsettings (§7) → Fcitx5's own trigger works.

LANG / LC_ALL not required. Fcitx + IBus do not require system locale = Chinese. Run LANG=en_US.UTF-8 + add Pinyin as secondary input method → recommended setup for English-primary users.

11. References