linux-im-diagnose 0.1.0

Diagnose input method (Fcitx/IBus) framework status for Linux applications

im-diagnose

Diagnose input method (Fcitx/IBus) framework status for Linux applications.

Inspects running processes via /proc to detect their UI framework (GTK3, GTK4, Qt5, Qt6, Electron), window system (X11, XWayland, Wayland), and whether the correct input method module is actually loaded.

Why?

Chinese/Japanese/Korean input on Linux is fragile. A common problem: you set GTK_IM_MODULE=fcitx, but an application silently loads IBus instead (or loads nothing). This tool tells you exactly what each application is doing at runtime.

Quick Start

# Inspect a specific process
python3 im_diagnose.py --pid $(pgrep -f firefox)

# Click a window to inspect (X11/XWayland)
python3 im_diagnose.py --click

# Scan all GUI processes (requires psutil)
python3 im_diagnose.py --all-gui

# Search by name (requires psutil)
python3 im_diagnose.py --search telegram

Installation

From PyPI (recommended):

# Basic install (--click and --pid work without extra dependencies)
pip install linux-im-diagnose

# With psutil for --search and --all-gui modes
pip install linux-im-diagnose[all]

# Or use pipx for isolated install
pipx install linux-im-diagnose[all]

# Or use uv
uv tool install linux-im-diagnose[all]

Then run: linux-im-diagnose --help

Standalone (single file, no install):

curl -O https://raw.githubusercontent.com/cliecy/linux-im-diagnose/main/im_diagnose.py
chmod +x im_diagnose.py
python3 im_diagnose.py --pid 12345

Usage

usage: im_diagnose.py [--click | --pid PID | --search NAME | --all-gui]
                      [--json] [-v] [--no-color] [--version]

Options:
  --click          Click a window to inspect (X11/XWayland)
  --pid PID        Inspect a specific PID
  --search NAME    Fuzzy search by process name (requires psutil)
  --all-gui        Scan all GUI processes (requires psutil)
  --json           Output as JSON
  -v, --verbose    Show loaded .so paths
  --no-color       Disable colored output

Default behavior: --click if DISPLAY is set, otherwise --all-gui.

Sample Output

IM Framework Diagnostic Report
========================================================================
D-Bus IM Services:  Fcitx5: inactive  |  Fcitx: active  |  IBus: active  (Current: sogoupinyin)

Process                  PID    WinSys  Framework      IM Config  IM Loaded  Health
-------------------------------------------------------------------------------------
cinnamon                 4514   X11     GTK3           fcitx      ibus       [WARN]
nemo-desktop             4601   X11     GTK3           fcitx      fcitx      [OK]
qq                       6368   X11     GTK3/Electron  fcitx      fcitx      [OK]
sogoupinyin-service      12020  X11     Qt5            fcitx      fcitx      [OK]
x-terminal-emulator      13785  X11     GTK4           fcitx      ibus       [WARN]

Warnings:
  cinnamon (4514):
    -> GTK_IM_MODULE=fcitx but ibus module loaded instead.
  x-terminal-emulator (13785):
    -> GTK_IM_MODULE=fcitx but ibus module loaded instead. GTK4 dropped GTK_IM_MODULE support; it uses ibus by default.

What It Detects

Category	Details
UI Framework	GTK3, GTK4, Qt5, Qt6, Electron, Chromium
Container	Flatpak, Snap
Window System	X11, XWayland, Wayland Native
IM Environment	GTK_IM_MODULE, QT_IM_MODULE, QT_IM_MODULES, XMODIFIERS, etc.
IM Loaded	Actual .so modules loaded in process memory (fcitx/ibus)
D-Bus Services	Fcitx5, Fcitx, IBus daemon status

Health Status

Status	Meaning
[OK]	IM configuration matches loaded modules
[WARN]	Mismatch or missing module (may be expected for daemons)
[??]	No IM configuration detected

Known Cases

• GTK4 apps showing ibus when fcitx is configured: GTK4 removed GTK_IM_MODULE support. It uses IBus by default via the Wayland IM protocol. This is expected behavior.
• Electron apps with no IM loaded: Electron may need --enable-wayland-ime or --gtk-version=4 flags.
• Flatpak/Snap apps with no IM module: The IM module may not be installed inside the sandbox runtime.

Requirements

• Python 3.8+
• Linux with /proc filesystem
• Optional: psutil (for --search and --all-gui modes)
• Optional: xprop (for --click mode on X11)

D-Bus Tools

The tool tries busctl (systemd) first, then falls back to dbus-send for non-systemd systems. If neither is available, D-Bus service detection is skipped.

License

MIT