Fcitx - User contributions [en]

Fcitx 5/zh-cn

2025-07-08T13:09:40Z

FuzzyBot: Updating to match new version of source page

<languages/>

小企鹅输入法（Fcitx 读作[ˈfaɪtɪks]）是一个支持扩展的输入法框架。目前，它支持Linux操作系统，以及如freebsd这样的Unix操作系统。Fcitx 通过使用各种各样的输入法引擎来支持全世界大量不同种类的语言。

Fcitx本身的核心实现非常简单，它通过使用插件来提供强大的功能。fcitx可以非常容易的进行定制以满足不同的个性化需求。

[[Special:myLanguage/Fcitx|导航至旧版的 Fcitx 4 Wiki页面?]]

==== 用户 ====

* [[Special:myLanguage/Install Fcitx 5|如何安装 Fcitx 5]]
* [[Special:myLanguage/Setup Fcitx 5|设置 Fcitx 5]]
* 安装 [[Special:myLanguage/Input method engines|输入法引擎]]
* [[Special:myLanguage/Theme Customization|定制您的输入法主题]]
* [[Special:myLanguage/FAQ|常见问题]]
* [[Special:myLanguage/Using Fcitx 5 on Wayland|在 Wayland 上使用 Fcitx 5]]
* [[Special:myLanguage/Tips and Tricks|使用技巧]]
* [[Special:myLanguage/Upgrade from Fcitx 4|从 Fcitx 4 升级]]

==== 开发者 ====

* [[Special:myLanguage/Compiling fcitx5|如何编译 fcitx5]]
* [[Special:myLanguage/Basic concept|基本概念]]
* [[Special:myLanguage/Develop an simple input method|如何开发一个简单的输入法]]
* [[Special:myLanguage/Q&A for developer|开发者常见问题与解答]]
* [[Special:myLanguage/Debug fcitx5|调试 fcitx5]]

==== 新闻 ====

<div class="mw-translate-fuzzy">
<rss max=5>https://github.com/fcitx/fcitx5/releases.atom</rss>
</div>

== 如何帮助 Fcitx ==
* 给你的朋友推荐Fcitx输入法
* [[Special:myLanguage/Report Bug|报告漏洞]]
* [[Special:myLanguage/Contribute to this Wiki|为Wiki做贡献]] ('''请在申请你的帐号之前仔细阅读此页面''')
* [[Special:myLanguage/Donate|捐助]]

== 关于 ==
* [[Special:myLanguage/History|Fcitx的历史]]

Fcitx 5/en

2025-07-08T13:09:34Z

FuzzyBot: Updating to match new version of source page

<languages/>

Fcitx [ˈfaɪtɪks] is an input method framework with extension support. Currently it supports Linux and Unix systems like freebsd. Fcitx supports typing with many languages all over the world with a large number of engines.

Fcitx has a slim core while provides powerful features with addons. It is easy to customize fcitx to satisfy your own needs.

[[Special:myLanguage/Fcitx|Looking for Old Wiki Page for Fcitx 4?]]

==== For Users ====

* [[Special:myLanguage/Install Fcitx 5|Install Fcitx 5]]
* [[Special:myLanguage/Setup Fcitx 5|Setup Fcitx 5]]
* Install [[Special:myLanguage/Input method engines|Input method engines]]
* [[Special:myLanguage/Theme Customization|Theme Customization]]
* [[Special:myLanguage/FAQ|FAQ]]
* [[Special:myLanguage/Using Fcitx 5 on Wayland|Using Fcitx 5 on Wayland]]
* [[Special:myLanguage/Tips and Tricks|Tips and Tricks]]
* [[Special:myLanguage/Upgrade from Fcitx 4|Upgrade from Fcitx 4]]

==== For Developers ====

* [[Special:myLanguage/Compiling fcitx5|Compiling fcitx5]]
* [[Special:myLanguage/Basic concept|Basic concept]]
* [[Special:myLanguage/Develop an simple input method|Develop an simple input method]]
* [[Special:myLanguage/Q&A for developer|Q&A for developer]]
* [[Special:myLanguage/Debug fcitx5|Debug fcitx5]]

==== News ====

<rss max=5 template="Template:GithubAtom">https://github.com/fcitx/fcitx5/releases.atom</rss>

== Help Fcitx ==
* Recommend Fcitx to your friend
* [[Special:myLanguage/Report Bug|Report Bug]]
* [[Special:myLanguage/Contribute to this Wiki|Contribute to this Wiki]] ('''Please read this before you request account''')
* [[Special:myLanguage/Donate|Donate]]

== About Fcitx ==
* [[Special:myLanguage/History|History]]

Translations:Fcitx 5/9/en

2025-07-08T13:09:29Z

FuzzyBot: Importing a new version from external source

<rss max=5 template="Template:GithubAtom">https://github.com/fcitx/fcitx5/releases.atom</rss>

Using Fcitx 5 on Wayland/en

2025-06-11T05:49:33Z

FuzzyBot: Updating to match new version of source page

<languages />
[https://wayland.freedesktop.org/ Wayland] is the next generation of display server protocol. While the initial release of the protocol is in 2008, the support of input method is not really ideal.

Also, using input method on Wayland-based compositor may require different setup to make it work, and certain features of fcitx that works under X11 are not yet supported by Wayland.

This page will try to cover all the current information with some underlying details, and [[Special:MyLanguage/Setup Fcitx 5|Setup Fcitx 5]] is still generally useful.

== Applications ==
=== TL;DR Do we still need XMODIFIERS, GTK_IM_MODULE and QT_IM_MODULE? ===

==== XMODIFIERS ====
For XMODIFIERS, yes, we do. X11 application running under X11 and XWayland has nearly no difference.

==== GTK_IM_MODULE ====
In an ideal setup, you should use fcitx im module Gtk application running under X11, and Gtk's text-input-v3 for wayland. The way of doing this is:

1. Do NOT set GTK_IM_MODULE environment variable.

2. For Gtk2, Add following content to ~/.gtkrc-2.0

<nowiki>gtk-im-module="fcitx"</nowiki>
3. For Gtk 3, add following content to ~/.config/gtk-3.0/settings.ini

<nowiki>[Settings]
gtk-im-module=fcitx</nowiki>

4. For Gtk 4, add following content to ~/.config/gtk-4.0/settings.ini

<nowiki>[Settings]
gtk-im-module=fcitx</nowiki>

5. If you are using GNOME 3+, also run following command.

<nowiki>gsettings set org.gnome.settings-daemon.plugins.xsettings overrides "{'Gtk/IMModule':<'fcitx'>}"</nowiki>

For GTK_IM_MODULE, as for now, the modern Gtk 3/4 application should be able to use text-input-v3 which is supported almost by every compositor, except weston. There are a few different options in terms of setting the value of GTK_IM_MODULE. When it is unset, the Gtk built-in Wayland im module will be used for Gtk3 and Gtk4. While you can also enforce it by doing GTK_IM_MODULE=wayland, remember it will be also picked up by Gtk2. Setting GTK_IM_MODULE=fcitx can still work, and it is necessary if your compositor does not support Wayland input method frontend.

It is possible to force a certain im module with Gtk configuration file, so without GTK_IM_MODULE set, it will still be able to use different im module.

Per Gtk implementation (still valid for 3.24.41), the order of preferences is:

* X11
** GTK_IM_MODULE in the environment
** Value of Gtk/IMModule from XSettings
** Value from configuration file
** A locale based automatic selection
* Wayland
** GTK_IM_MODULE in the environment
** "wayland"

==== QT_IM_MODULE ====
For QT_IM_MODULE, as for now QT can only use its own text-input-v{2,4}, which is only supported by KWin. Which means, under KDE you should unset it, but under other desktop, you will need to set it to QT_IM_MODULE=fcitx. Also the proprietary Qt applications in the wild complicates the situation. Some do not work on Wayland, some do not bundle/provide Qt wayland. Most of them do not bundle fcitx im module because fcitx is only a third party application to Qt, but I also noticed some do bundle but not bundle all the required libraries. While fcitx 5 support ibus protocol, some of those applications do not even bundle ibus im module. There are a few different environment variables you can try for those proprietary Qt applications (WPS, Anki, DaVinci Resolve, Mathematica, etc...).

<nowiki>QT_IM_MODULE=fcitx # For those who bundle qt im module, e.g. WPS, Anki, you should find a .so file with fcitx in the file name
QT_IM_MODULE=ibus # For those who bundle ibus im module shipped with Qt, you should find libibusplatforminputcontextplugin.so in the package.
QT_QPA_PLATFORM=xcb QT_IM_MODULE=ibus # Enforce it to run on X11/XWayland and use ibus im module
</nowiki>

In Qt 6.7, there is a new environment variable called "QT_IM_MODULES", which allows you so specify a fallback order on im modules. You can set it to

<nowiki>QT_IM_MODULES="wayland;fcitx;ibus"</nowiki>

So it will be able pick up the most usable one even for application that bundles no fcitx/wayland. Remember, you may still need to set( or unset) QT_IM_MODULE (not "QT_IM_MODULES") in order to handle Qt 4/5 applications.

=== Legacy X11 application that runs under XWayland ===
In a word, XWayland support for input method is as good as normal X11 display server. As long as you set the same environment variable, using Xwayland should not be a issue. This category includes:

* Xlib-based (and also other toolkit based on Xlib, e.g. tk, SDL1, etc), e.g. xterm, rxvt. Make sure XMODIFIERS is set correctly.
* Gtk2-based applications, similar to Xlib, but can use fcitx im module. Set GTK_IM_MODULE to fcitx will give it best experience.
* SDL2-based applications that doesn't default to wayland. Set SDL_IM_MODULE to fcitx
* electron, chromium, these are still default to X11, similar to Gtk2 case.
* For Qt4 applcation, Qt 4 can only use X11. You will need to QT_IM_MODULE to fcitx. Same for Qt5+ that uses XCB (can be override with QT_QPA_PLATFORM=xcb).

=== Gtk3 / Gtk4 ===
Gtk3 and Gtk4 support text-input-v3 natively. At the same time, it's also possible to use fcitx im module under wayland. So, either GTK_IM_MODULE=wayland or GTK_IM_MODULE=fcitx works. There are some difference to it. text-input-v3

=== Qt5 / Qt6 ===
If your Qt application natively runs under Wayland, you can either unset QT_IM_MODULE to make it use text-input-v2, or set QT_IM_MODULE=fcitx to make it use fcitx im module.

text-input-v2 is not upstreamed to wayland-protocols, that is probably why only kwin support it. This means in non-kwin environment, you will need to use QT_IM_MODULE=fcitx to make the Qt applications work.

On Qt6, you may also use QT_IM_MODULE= (empty) or QT_IM_MODULE=wayland if your Qt vesion contains this https://codereview.qt-project.org/c/qt/qtwayland/+/416862.

=== Native wayland application (winit) ===
Most likely text-input-v3 is being used.

=== Chromium / Electron ===
{{warning|The information in this section may not be up to date to reflect upstream change, especially the default behavior when no option is changed.}}
TL;DR version, if you use XWayland to run Chromium or Electron application, just install Gtk im module and GTK_IM_MODULE=fcitx the same way like X11.

If you choose to run it natively under Wayland, for chromium you will need to use

# If your compositor supports text-input-v1 protocol. Check the compositor section below.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

# If your compositor & chromium supports text-input-v3 protocol, you may also use
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime --wayland-text-input-version=3

# However, due to a different understanding in text-input-v3 protocol, it has some issue when using with KWin.
# Prefer text-input-v1 if you're using kwin.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime --wayland-text-input-version=1

Or

# You will get wrong position for the input method popup window, unless you use GNOME shell + kimpanel extension.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --gtk-version=4

For electron, only the first option is avaiable (electron does NOT support to run internal chromium with gtk4), e.g. for vscode

# If your compositor supports text-input-v1 protocol. Check the compositor section below.
code --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

By default it should run under Xwayland (As of 2023/02/25 on Archlinux/Chromium 110.0.5481.177), but some user also reports it is using wayland even the "Preferred Ozone Platform" is "Default". So to check whether it's really run with wayland, you can use xeyes or xwininfo. With xeyes, if it's an X11 window, the "eyes" will move with mouse, otherwise it's wayland. With xwininfo, if the mouse cursor changed to "+" shape, and click the window shows the window information, then it is a X11 window.

You may force it to run with Wayland, or X11 with the flag <code>--ozone-platform=wayland</code> and <code>--ozone-platform=x11</code>. You may persistent this by changing the option "Preferred Ozone Platform" in chrome://flags. It has four values, "Default", "X11", "Wayland", "Auto".

It's possible to make it use GTK_IM_MODULE if it runs with Gtk4 (only supported by chromium/chrome at this time, not electron) by passing <code>--gtk-version=4</code>.

It's also possible to make it use text-input-v1 by passing <code>--enable-wayland-ime</code> in addition to the flag above.

The Chromium support for text-input-v1 is not very stable and you may hit some random crash. E.g. in the past, version 112 has a crash bug: https://bugs.chromium.org/p/chromium/issues/detail?id=1431532 , which is fixed in version 115. In the bug comment, Chromium developer claims this text-input-v1 is only supposed to be used internally and not well supported, so use this at your own risk though it's currently the only out of box option.

You should only use one of <code>--enable-wayland-ime</code> or <code>--gtk-version=4</code>, depending on you want to use text-input-v1, or gtk4 im module. text-input-v1 works for kwin 5.27 and weston. Gtk4 im module works on all environment, but only GNOME with Kimpanel extension can display the popup window in the correct position.

== Support in Wayland Compositor ==

Even if you are using only native wayland applications, Xwayland is recommended to be enabled for following reason. If client side input panel in im module does not work, fcitx will fallback to a X11 window, instead of a wayland window. The reason for this is because wayland window can not be placed freely on the screen. On the contrary, even if im module can only pass a coordinate relative to the application window to fcitx, which make the coordinate position doesn't make much sense, if your application window size is "maximized", the coordinate may just be "right" if treated as the global coordinate. This makes X11 window a better option than a randomly placed wayland window.

=== KDE Plasma ===
Best setup:
* KDE Plasma 5.27 or later
* Environment variables:
** Set <code>XMODIFIERS=@im=fcitx</code> for XWayland application
** Start fcitx5 by go to "System settings" -> "Virtual keyboard" -> Select Fcitx 5
** Do not set <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> & <code>SDL_IM_MODULE</code> . You could unset <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> by runing <code>im-config</code> and then selecting <code>do not set any IM from im-config and use desktop default"</code>
** Run chromium/electron application with <code>--enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime</code>
* Caveats:
** Certain Gtk/Qt application that only works under X11 may still need to set <code>GTK_IM_MODULE</code> or <code>QT_IM_MODULE</code> for them individually.
** If you set <code>GTK_IM_MODULE/QT_IM_MODULE</code> globally, you will hit this issue [[Special:MyLanguage/FAQ#Candidate_window_is_blinking_under_wayland_with_Fcitx_5|Candidate window is blinking under wayland with Fcitx 5]]

Support Information:
* App/Compositor supports text-input-v2 and text-input-v3.
* Comopositor/Application uses zwp_input_method_v1.
* 5.27 additionally supports text-input-v1.
* 5.24 usable zwp_input_method_v1 with fcitx5. Pre-5.24 there are lots of problems, always use fcitx im module instead.
* Use "Virtual keyboard" KCM to launch fcitx5. This is required to use text-input protocol. If you launch fcitx this way, make sure you do not use "restart" in the tray menu, since the socket passed from KWin can not be reused with the newly restarted fcitx.

=== GNOME ===
Best setup:
* Environment variables:
** Set <code>XMODIFIERS=@im=fcitx</code> for XWayland application
** Set <code>QT_IM_MODULE=fcitx</code> for Qt, since Qt5 would use XWayland by default.
** Run chrome with XWayland and <code>GTK_IM_MODULE=fcitx</code>

Support information:
* Application/Compositor uses text-input-v3
* Compositor/Input Method uses ibus dbus protocol, so ibus frontend is required to be used.
* Adding Fcitx 5 to autostart, it will replace any existing ibus-daemon upon start up so it will work out of box.
* Popup candidate window is not able to be displayed over gnome-shell UI. Only solution is to use [[Special:MyLanguage/Kimpanel|Kimpanel]], [https://extensions.gnome.org/extension/261/kimpanel/ link to extension].
* Qt need to use QT_IM_MODULE=fcitx since there is no text-input-v2 support.

=== Sway ===
* Application/Compositor uses text-input-v3
* Comopositor/Application uses zwp_input_method_v2, but it's partially implemented. You will need [https://github.com/swaywm/sway/pull/7226 this pull request] to make it show the popup candidate window for text-input-v3 client.
* fcitx im module also works.
* Qt need to use QT_IM_MODULE=fcitx since there is no text-input-v2 support.

=== Weston ===
* Application/Compositor uses text-input-v1
* Comopositor/Application uses zwp_input_method_v1.
* Since it has no text-input-v3, which is more commonly used, im module is the only solution for Gtk/Qt, need to set GTK_IM_MODULE=fcitx and QT_IM_MODULE=fcitx.
* Add following content to ~/.config/weston.ini to make it launch fcitx 5. (xwayland part is recommended to make fcitx work best, even if it's wayland)

<pre>
[core]
xwayland=true

[input-method]
path=/usr/bin/fcitx5
</pre>

=== Other compositors ===
Please check their upstream for more information. For wlroots based compositors, it is possible that they also support in the same way as Sway does, or zwp_input_method could also be unsupported.

== Known Issues ==
=== Fcitx managed XKB layout ===
Unlike X11, there is no generic way to set XKB layout to compositor, which means it can only be implemented for every individual desktop. Right now, Fcitx managed layout only works for KDE Plasma and GNOME.

As for other desktop, in order to make this "semi" work you'll need to ensure following:

* The XKB layout of the input method group should be the same as the actual xkb layout you configured for the compositor. Fcitx will "think" the layout is the same and bypass the key conversion logic.
* If you need other layout for text typing (e.g. Arabic), just add them to the Fcitx. As long as the key is forwarded to fcitx, it should work.

=== Popup candidate window ===
Wayland does not have a global coordinate system for regular client, so for native wayland client, it is impossible for Fcitx to place a wayland surface at a certain position. In order for popup window to be placed at the correct position, there are following cases:
* Xwayland have no problem and it should work as good as X11.
* If zwp_input_method protocol can be used, it has a surface role to allow compositor to place the popup window for input method. This only works if client uses text-input protocol.
* For GNOME, kimpanel extension can read window coordinate since it's running inside compositor. As long as im module can report relative coordinate, kimpanel extension can display the popup window at the correct position. As similar approach for Plasma kimpanel is planned, but not yet implemented.
* For Gtk/Qt, fcitx's im module implement a way to render the popup with in the client process. This has some limitation because implemenation of xdg_popup in Gtk3/Qt5 doesn't support reposition the window. So show/hide trick is used to mitigate this, but it may cause window blinking. Fcitx tries not to move window if possible. You may also disable popup animation if you're using KWin to help reduce the blinking.

=== Per-window input method state ===
When zwp_input_method is used, essentially there is only one input context visible to fcitx, and fcitx cannot distinguish what application is being used. Which means the input method "active"/"inactivate" state is now "global".

Now fcitx supports two protocol to figure out the focused window and the corresponding application name, including wlr-foreign-toplevel-management (used by wlroots based compositor) and plasma-window-management (used by kwin).

Using Fcitx 5 on Wayland/zh-cn

2025-06-11T05:49:11Z

FuzzyBot: Updating to match new version of source page

<languages />
[https://wayland.freedesktop.org/ Wayland] is the next generation of display server protocol. While the initial release of the protocol is in 2008, the support of input method is not really ideal.

在不同的Wayland合成器上使用输入法可能需要不同的配置，且某些在X11下可用的Fcitx功能尚未被Wayland支持。

本文尽量涵盖目前所有的相关信息，[[Special:MyLanguage /Setup Fcitx 5|Fcitx 5配置指南]]亦仍具有参考价值。

== Applications ==
=== TLDR：还需要设置 XMODIFIERS，GTK_IM_MODULE 和 QT_IM_MODULE 吗? ===

XMODIFIERS 确实还需要设置，因为纯 X11 和 XWayland 下运行的 X11 程序基本没什么区别。

==== GTK_IM_MODULE ====
在理想的情况下，你应该在 X11 下运行的 GTK 程序用 im-module，而在纯 Wayland 程序中用 GTK 的 text-input-v3 支持。其方法是：

1. 不要设置 GTK_IM_MODULE 环境变量！

2. 对于 Gtk2，向 ~/.gtkrc-2.0 添加如下内容：

<nowiki>gtk-im-module="fcitx"</nowiki>
3. 对于 Gtk3，向 ~/.config/gtk-3.0/settings.ini 添加如下内容：

<nowiki>[Settings]
gtk-im-module=fcitx</nowiki>

4. 对于 Gtk4。向 ~/.config/gtk-4.0/settings.ini 添加如下内容：

<nowiki>[Settings]
gtk-im-module=fcitx</nowiki>

5. 如果你在用 GNOME 3 和以上版本，你还需要运行以下命令：

<nowiki>gsettings set org.gnome.settings-daemon.plugins.xsettings overrides "{'Gtk/IMModule':<'fcitx'>}"</nowiki>

关于 GTK_IM_MODULE 环境变量，目前现代 Gtk3/4 应用程序应当能够使用 text-input-v3 协议（该协议已被绝大多数合成器支持，Weston 除外）。不设置 GTK_IM_MODULE 的时候，Gtk3/Gtk4 就会自动启用内置的 Wayland 输入法模块。虽然你也可以显式指定 GTK_IM_MODULE=wayland，但是 Gtk2 程序也会读取这个环境变量，导致兼容问题。设置 GTK_IM_MODULE=fcitx 依然是可以工作的，而且如果你使用的合成器不兼容 Wayland 输入法协议，这也是你的唯一选择。

你可以在 Gtk 的配置文件里强制使用某个 IM Module，所以就算你不设置 GTK_IM_MODULE 环境变量也仍然是可以用不同的 IM Module 的。

根据 Gtk 的实现（截至 3.24.41 版本仍有效），优先级顺序如下：

* X11
** 环境变量中的 GTK_IM_MODULE
** XSettings 中 Gtk/IMModule 的值
** 配置文件中的值
** 基于区域设置的自动选择
* Wayland
** 环境变量中的 GTK_IM_MODULE
** "wayland"

==== QT_IM_MODULE ====
For QT_IM_MODULE, as for now QT can only use its own text-input-v{2,4}, which is only supported by KWin. Which means, under KDE you should unset it, but under other desktop, you will need to set it to QT_IM_MODULE=fcitx. Also the proprietary Qt applications in the wild complicates the situation. Some do not work on Wayland, some do not bundle/provide Qt wayland. Most of them do not bundle fcitx im module because fcitx is only a third party application to Qt, but I also noticed some do bundle but not bundle all the required libraries. While fcitx 5 support ibus protocol, some of those applications do not even bundle ibus im module. There are a few different environment variables you can try for those proprietary Qt applications (WPS, Anki, DaVinci Resolve, Mathematica, etc...).

<nowiki>QT_IM_MODULE=fcitx # For those who bundle qt im module, e.g. WPS, Anki, you should find a .so file with fcitx in the file name
QT_IM_MODULE=ibus # For those who bundle ibus im module shipped with Qt, you should find libibusplatforminputcontextplugin.so in the package.
QT_QPA_PLATFORM=xcb QT_IM_MODULE=ibus # Enforce it to run on X11/XWayland and use ibus im module
</nowiki>

In Qt 6.7, there is a new environment variable called "QT_IM_MODULES", which allows you so specify a fallback order on im modules. You can set it to

<nowiki>QT_IM_MODULES="wayland;fcitx;ibus"</nowiki>

So it will be able pick up the most usable one even for application that bundles no fcitx/wayland. Remember, you may still need to set( or unset) QT_IM_MODULE (not "QT_IM_MODULES") in order to handle Qt 4/5 applications.

=== Legacy X11 application that runs under XWayland ===
In a word, XWayland support for input method is as good as normal X11 display server. As long as you set the same environment variable, using Xwayland should not be a issue. This category includes:

* Xlib-based (and also other toolkit based on Xlib, e.g. tk, SDL1, etc), e.g. xterm, rxvt. Make sure XMODIFIERS is set correctly.
* Gtk2-based applications, similar to Xlib, but can use fcitx im module. Set GTK_IM_MODULE to fcitx will give it best experience.
* SDL2-based applications that doesn't default to wayland. Set SDL_IM_MODULE to fcitx
* electron, chromium, these are still default to X11, similar to Gtk2 case.
* For Qt4 applcation, Qt 4 can only use X11. You will need to QT_IM_MODULE to fcitx. Same for Qt5+ that uses XCB (can be override with QT_QPA_PLATFORM=xcb).

=== Gtk3 / Gtk4 ===
Gtk3 and Gtk4 support text-input-v3 natively. At the same time, it's also possible to use fcitx im module under wayland. So, either GTK_IM_MODULE=wayland or GTK_IM_MODULE=fcitx works. There are some difference to it. text-input-v3

=== Qt5 / Qt6 ===
If your Qt application natively runs under Wayland, you can either unset QT_IM_MODULE to make it use text-input-v2, or set QT_IM_MODULE=fcitx to make it use fcitx im module.

text-input-v2 is not upstreamed to wayland-protocols, that is probably why only kwin support it. This means in non-kwin environment, you will need to use QT_IM_MODULE=fcitx to make the Qt applications work.

On Qt6, you may also use QT_IM_MODULE= (empty) or QT_IM_MODULE=wayland if your Qt vesion contains this https://codereview.qt-project.org/c/qt/qtwayland/+/416862.

=== Native wayland application (winit) ===
Most likely text-input-v3 is being used.

=== Chromium / Electron ===
{{warning|The information in this section may not be up to date to reflect upstream change, especially the default behavior when no option is changed.}}
TL;DR version, if you use XWayland to run Chromium or Electron application, just install Gtk im module and GTK_IM_MODULE=fcitx the same way like X11.

If you choose to run it natively under Wayland, for chromium you will need to use

# If your compositor supports text-input-v1 protocol. Check the compositor section below.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

# If your compositor & chromium supports text-input-v3 protocol, you may also use
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime --wayland-text-input-version=3

# However, due to a different understanding in text-input-v3 protocol, it has some issue when using with KWin.
# Prefer text-input-v1 if you're using kwin.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime --wayland-text-input-version=1

Or

# You will get wrong position for the input method popup window, unless you use GNOME shell + kimpanel extension.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --gtk-version=4

For electron, only the first option is avaiable (electron does NOT support to run internal chromium with gtk4), e.g. for vscode

# If your compositor supports text-input-v1 protocol. Check the compositor section below.
code --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

By default it should run under Xwayland (As of 2023/02/25 on Archlinux/Chromium 110.0.5481.177), but some user also reports it is using wayland even the "Preferred Ozone Platform" is "Default". So to check whether it's really run with wayland, you can use xeyes or xwininfo. With xeyes, if it's an X11 window, the "eyes" will move with mouse, otherwise it's wayland. With xwininfo, if the mouse cursor changed to "+" shape, and click the window shows the window information, then it is a X11 window.

You may force it to run with Wayland, or X11 with the flag <code>--ozone-platform=wayland</code> and <code>--ozone-platform=x11</code>. You may persistent this by changing the option "Preferred Ozone Platform" in chrome://flags. It has four values, "Default", "X11", "Wayland", "Auto".

It's possible to make it use GTK_IM_MODULE if it runs with Gtk4 (only supported by chromium/chrome at this time, not electron) by passing <code>--gtk-version=4</code>.

It's also possible to make it use text-input-v1 by passing <code>--enable-wayland-ime</code> in addition to the flag above.

The Chromium support for text-input-v1 is not very stable and you may hit some random crash. E.g. in the past, version 112 has a crash bug: https://bugs.chromium.org/p/chromium/issues/detail?id=1431532 , which is fixed in version 115. In the bug comment, Chromium developer claims this text-input-v1 is only supposed to be used internally and not well supported, so use this at your own risk though it's currently the only out of box option.

You should only use one of <code>--enable-wayland-ime</code> or <code>--gtk-version=4</code>, depending on you want to use text-input-v1, or gtk4 im module. text-input-v1 works for kwin 5.27 and weston. Gtk4 im module works on all environment, but only GNOME with Kimpanel extension can display the popup window in the correct position.

== Support in Wayland Compositor ==

Even if you are using only native wayland applications, Xwayland is recommended to be enabled for following reason. If client side input panel in im module does not work, fcitx will fallback to a X11 window, instead of a wayland window. The reason for this is because wayland window can not be placed freely on the screen. On the contrary, even if im module can only pass a coordinate relative to the application window to fcitx, which make the coordinate position doesn't make much sense, if your application window size is "maximized", the coordinate may just be "right" if treated as the global coordinate. This makes X11 window a better option than a randomly placed wayland window.

=== KDE Plasma ===
Best setup:
* KDE Plasma 5.27 or later
* Environment variables:
** Set <code>XMODIFIERS=@im=fcitx</code> for XWayland application
** Start fcitx5 by go to "System settings" -> "Virtual keyboard" -> Select Fcitx 5
** Do not set <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> & <code>SDL_IM_MODULE</code> . You could unset <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> by runing <code>im-config</code> and then selecting <code>do not set any IM from im-config and use desktop default"</code>
** Run chromium/electron application with <code>--enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime</code>
* Caveats:
** Certain Gtk/Qt application that only works under X11 may still need to set <code>GTK_IM_MODULE</code> or <code>QT_IM_MODULE</code> for them individually.
** If you set <code>GTK_IM_MODULE/QT_IM_MODULE</code> globally, you will hit this issue [[Special:MyLanguage/FAQ#Candidate_window_is_blinking_under_wayland_with_Fcitx_5|Candidate window is blinking under wayland with Fcitx 5]]

Support Information:
* App/Compositor supports text-input-v2 and text-input-v3.
* Comopositor/Application uses zwp_input_method_v1.
* 5.27 additionally supports text-input-v1.
* 5.24 usable zwp_input_method_v1 with fcitx5. Pre-5.24 there are lots of problems, always use fcitx im module instead.
* Use "Virtual keyboard" KCM to launch fcitx5. This is required to use text-input protocol. If you launch fcitx this way, make sure you do not use "restart" in the tray menu, since the socket passed from KWin can not be reused with the newly restarted fcitx.

=== GNOME ===
Best setup:
* Environment variables:
** Set <code>XMODIFIERS=@im=fcitx</code> for XWayland application
** Set <code>QT_IM_MODULE=fcitx</code> for Qt, since Qt5 would use XWayland by default.
** Run chrome with XWayland and <code>GTK_IM_MODULE=fcitx</code>

Support information:
* Application/Compositor uses text-input-v3
* Compositor/Input Method uses ibus dbus protocol, so ibus frontend is required to be used.
* Adding Fcitx 5 to autostart, it will replace any existing ibus-daemon upon start up so it will work out of box.
* Popup candidate window is not able to be displayed over gnome-shell UI. Only solution is to use [[Special:MyLanguage/Kimpanel|Kimpanel]], [https://extensions.gnome.org/extension/261/kimpanel/ link to extension].
* Qt need to use QT_IM_MODULE=fcitx since there is no text-input-v2 support.

=== Sway ===
* Application/Compositor uses text-input-v3
* Comopositor/Application uses zwp_input_method_v2, but it's partially implemented. You will need [https://github.com/swaywm/sway/pull/7226 this pull request] to make it show the popup candidate window for text-input-v3 client.
* fcitx im module also works.
* Qt need to use QT_IM_MODULE=fcitx since there is no text-input-v2 support.

=== Weston ===
* Application/Compositor uses text-input-v1
* Comopositor/Application uses zwp_input_method_v1.
* Since it has no text-input-v3, which is more commonly used, im module is the only solution for Gtk/Qt, need to set GTK_IM_MODULE=fcitx and QT_IM_MODULE=fcitx.
* Add following content to ~/.config/weston.ini to make it launch fcitx 5. (xwayland part is recommended to make fcitx work best, even if it's wayland)

<pre>
[core]
xwayland=true

[input-method]
path=/usr/bin/fcitx5
</pre>

=== Other compositors ===
Please check their upstream for more information. For wlroots based compositors, it is possible that they also support in the same way as Sway does, or zwp_input_method could also be unsupported.

== Known Issues ==
=== Fcitx managed XKB layout ===
Unlike X11, there is no generic way to set XKB layout to compositor, which means it can only be implemented for every individual desktop. Right now, Fcitx managed layout only works for KDE Plasma and GNOME.

As for other desktop, in order to make this "semi" work you'll need to ensure following:

* The XKB layout of the input method group should be the same as the actual xkb layout you configured for the compositor. Fcitx will "think" the layout is the same and bypass the key conversion logic.
* If you need other layout for text typing (e.g. Arabic), just add them to the Fcitx. As long as the key is forwarded to fcitx, it should work.

=== Popup candidate window ===
Wayland does not have a global coordinate system for regular client, so for native wayland client, it is impossible for Fcitx to place a wayland surface at a certain position. In order for popup window to be placed at the correct position, there are following cases:
* Xwayland have no problem and it should work as good as X11.
* If zwp_input_method protocol can be used, it has a surface role to allow compositor to place the popup window for input method. This only works if client uses text-input protocol.
* For GNOME, kimpanel extension can read window coordinate since it's running inside compositor. As long as im module can report relative coordinate, kimpanel extension can display the popup window at the correct position. As similar approach for Plasma kimpanel is planned, but not yet implemented.
* For Gtk/Qt, fcitx's im module implement a way to render the popup with in the client process. This has some limitation because implemenation of xdg_popup in Gtk3/Qt5 doesn't support reposition the window. So show/hide trick is used to mitigate this, but it may cause window blinking. Fcitx tries not to move window if possible. You may also disable popup animation if you're using KWin to help reduce the blinking.

=== Per-window input method state ===
When zwp_input_method is used, essentially there is only one input context visible to fcitx, and fcitx cannot distinguish what application is being used. Which means the input method "active"/"inactivate" state is now "global".

Now fcitx supports two protocol to figure out the focused window and the corresponding application name, including wlr-foreign-toplevel-management (used by wlroots based compositor) and plasma-window-management (used by kwin).

Translations:Using Fcitx 5 on Wayland/48/en

2025-06-11T05:49:07Z

FuzzyBot: Importing a new version from external source

=== KDE Plasma ===
Best setup:
* KDE Plasma 5.27 or later
* Environment variables:
** Set <code>XMODIFIERS=@im=fcitx</code> for XWayland application
** Start fcitx5 by go to "System settings" -> "Virtual keyboard" -> Select Fcitx 5
** Do not set <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> & <code>SDL_IM_MODULE</code> . You could unset <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> by runing <code>im-config</code> and then selecting <code>do not set any IM from im-config and use desktop default"</code>
** Run chromium/electron application with <code>--enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime</code>
* Caveats:
** Certain Gtk/Qt application that only works under X11 may still need to set <code>GTK_IM_MODULE</code> or <code>QT_IM_MODULE</code> for them individually.
** If you set <code>GTK_IM_MODULE/QT_IM_MODULE</code> globally, you will hit this issue [[Special:MyLanguage/FAQ#Candidate_window_is_blinking_under_wayland_with_Fcitx_5|Candidate window is blinking under wayland with Fcitx 5]]

Using Fcitx 5 on Wayland/zh-cn

2025-03-04T11:44:49Z

FuzzyBot: Updating to match new version of source page

<languages />
[https://wayland.freedesktop.org/ Wayland] is the next generation of display server protocol. While the initial release of the protocol is in 2008, the support of input method is not really ideal.

Also, using input method on Wayland-based compositor may require different setup to make it work, and certain features of fcitx that works under X11 are not yet supported by Wayland.

This page will try to cover all the current information with some underlying details, and [[Special:MyLanguage/Setup Fcitx 5|Setup Fcitx 5]] is still generally useful.

== Applications ==
=== TL;DR Do we still need XMODIFIERS, GTK_IM_MODULE and QT_IM_MODULE? ===

==== XMODIFIERS ====
For XMODIFIERS, yes, we do. X11 application running under X11 and XWayland has nearly no difference.

==== GTK_IM_MODULE ====
In an ideal setup, you should use fcitx im module Gtk application running under X11, and Gtk's text-input-v3 for wayland. The way of doing this is:

1. Do NOT set GTK_IM_MODULE environment variable.

2. For Gtk2, Add following content to ~/.gtkrc-2.0

<nowiki>gtk-im-module="fcitx"</nowiki>
3. For Gtk 3, add following content to ~/.config/gtk-3.0/settings.ini

<nowiki>[Settings]
gtk-im-module=fcitx</nowiki>

4. For Gtk 4, add following content to ~/.config/gtk-4.0/settings.ini

<nowiki>[Settings]
gtk-im-module=fcitx</nowiki>

5. If you are using GNOME 3+, also run following command.

<nowiki>gsettings set org.gnome.settings-daemon.plugins.xsettings overrides "{'Gtk/IMModule':<'fcitx'>}"</nowiki>

For GTK_IM_MODULE, as for now, the modern Gtk 3/4 application should be able to use text-input-v3 which is supported almost by every compositor, except weston. There are a few different options in terms of setting the value of GTK_IM_MODULE. When it is unset, the Gtk built-in Wayland im module will be used for Gtk3 and Gtk4. While you can also enforce it by doing GTK_IM_MODULE=wayland, remember it will be also picked up by Gtk2. Setting GTK_IM_MODULE=fcitx can still work, and it is necessary if your compositor does not support Wayland input method frontend.

It is possible to force a certain im module with Gtk configuration file, so without GTK_IM_MODULE set, it will still be able to use different im module.

Per Gtk implementation (still valid for 3.24.41), the order of preferences is:

* X11
** GTK_IM_MODULE in the environment
** Value of Gtk/IMModule from XSettings
** Value from configuration file
** A locale based automatic selection
* Wayland
** GTK_IM_MODULE in the environment
** "wayland"

==== QT_IM_MODULE ====
For QT_IM_MODULE, as for now QT can only use its own text-input-v{2,4}, which is only supported by KWin. Which means, under KDE you should unset it, but under other desktop, you will need to set it to QT_IM_MODULE=fcitx. Also the proprietary Qt applications in the wild complicates the situation. Some do not work on Wayland, some do not bundle/provide Qt wayland. Most of them do not bundle fcitx im module because fcitx is only a third party application to Qt, but I also noticed some do bundle but not bundle all the required libraries. While fcitx 5 support ibus protocol, some of those applications do not even bundle ibus im module. There are a few different environment variables you can try for those proprietary Qt applications (WPS, Anki, DaVinci Resolve, Mathematica, etc...).

<nowiki>QT_IM_MODULE=fcitx # For those who bundle qt im module, e.g. WPS, Anki, you should find a .so file with fcitx in the file name
QT_IM_MODULE=ibus # For those who bundle ibus im module shipped with Qt, you should find libibusplatforminputcontextplugin.so in the package.
QT_QPA_PLATFORM=xcb QT_IM_MODULE=ibus # Enforce it to run on X11/XWayland and use ibus im module
</nowiki>

In Qt 6.7, there is a new environment variable called "QT_IM_MODULES", which allows you so specify a fallback order on im modules. You can set it to

<nowiki>QT_IM_MODULES="wayland;fcitx;ibus"</nowiki>

So it will be able pick up the most usable one even for application that bundles no fcitx/wayland. Remember, you may still need to set( or unset) QT_IM_MODULE (not "QT_IM_MODULES") in order to handle Qt 4/5 applications.

=== Legacy X11 application that runs under XWayland ===
In a word, XWayland support for input method is as good as normal X11 display server. As long as you set the same environment variable, using Xwayland should not be a issue. This category includes:

* Xlib-based (and also other toolkit based on Xlib, e.g. tk, SDL1, etc), e.g. xterm, rxvt. Make sure XMODIFIERS is set correctly.
* Gtk2-based applications, similar to Xlib, but can use fcitx im module. Set GTK_IM_MODULE to fcitx will give it best experience.
* SDL2-based applications that doesn't default to wayland. Set SDL_IM_MODULE to fcitx
* electron, chromium, these are still default to X11, similar to Gtk2 case.
* For Qt4 applcation, Qt 4 can only use X11. You will need to QT_IM_MODULE to fcitx. Same for Qt5+ that uses XCB (can be override with QT_QPA_PLATFORM=xcb).

=== Gtk3 / Gtk4 ===
Gtk3 and Gtk4 support text-input-v3 natively. At the same time, it's also possible to use fcitx im module under wayland. So, either GTK_IM_MODULE=wayland or GTK_IM_MODULE=fcitx works. There are some difference to it. text-input-v3

=== Qt5 / Qt6 ===
If your Qt application natively runs under Wayland, you can either unset QT_IM_MODULE to make it use text-input-v2, or set QT_IM_MODULE=fcitx to make it use fcitx im module.

text-input-v2 is not upstreamed to wayland-protocols, that is probably why only kwin support it. This means in non-kwin environment, you will need to use QT_IM_MODULE=fcitx to make the Qt applications work.

On Qt6, you may also use QT_IM_MODULE= (empty) or QT_IM_MODULE=wayland if your Qt vesion contains this https://codereview.qt-project.org/c/qt/qtwayland/+/416862.

=== Native wayland application (winit) ===
Most likely text-input-v3 is being used.

=== Chromium / Electron ===
{{warning|The information in this section may not be up to date to reflect upstream change, especially the default behavior when no option is changed.}}
TL;DR version, if you use XWayland to run Chromium or Electron application, just install Gtk im module and GTK_IM_MODULE=fcitx the same way like X11.

If you choose to run it natively under Wayland, for chromium you will need to use

# If your compositor supports text-input-v1 protocol. Check the compositor section below.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

# If your compositor & chromium supports text-input-v3 protocol, you may also use
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime --wayland-text-input-version=3

# However, due to a different understanding in text-input-v3 protocol, it has some issue when using with KWin.
# Prefer text-input-v1 if you're using kwin.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime --wayland-text-input-version=1

Or

# You will get wrong position for the input method popup window, unless you use GNOME shell + kimpanel extension.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --gtk-version=4

For electron, only the first option is avaiable (electron does NOT support to run internal chromium with gtk4), e.g. for vscode

# If your compositor supports text-input-v1 protocol. Check the compositor section below.
code --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

By default it should run under Xwayland (As of 2023/02/25 on Archlinux/Chromium 110.0.5481.177), but some user also reports it is using wayland even the "Preferred Ozone Platform" is "Default". So to check whether it's really run with wayland, you can use xeyes or xwininfo. With xeyes, if it's an X11 window, the "eyes" will move with mouse, otherwise it's wayland. With xwininfo, if the mouse cursor changed to "+" shape, and click the window shows the window information, then it is a X11 window.

You may force it to run with Wayland, or X11 with the flag <code>--ozone-platform=wayland</code> and <code>--ozone-platform=x11</code>. You may persistent this by changing the option "Preferred Ozone Platform" in chrome://flags. It has four values, "Default", "X11", "Wayland", "Auto".

It's possible to make it use GTK_IM_MODULE if it runs with Gtk4 (only supported by chromium/chrome at this time, not electron) by passing <code>--gtk-version=4</code>.

It's also possible to make it use text-input-v1 by passing <code>--enable-wayland-ime</code> in addition to the flag above.

The Chromium support for text-input-v1 is not very stable and you may hit some random crash. E.g. in the past, version 112 has a crash bug: https://bugs.chromium.org/p/chromium/issues/detail?id=1431532 , which is fixed in version 115. In the bug comment, Chromium developer claims this text-input-v1 is only supposed to be used internally and not well supported, so use this at your own risk though it's currently the only out of box option.

You should only use one of <code>--enable-wayland-ime</code> or <code>--gtk-version=4</code>, depending on you want to use text-input-v1, or gtk4 im module. text-input-v1 works for kwin 5.27 and weston. Gtk4 im module works on all environment, but only GNOME with Kimpanel extension can display the popup window in the correct position.

== Support in Wayland Compositor ==

Even if you are using only native wayland applications, Xwayland is recommended to be enabled for following reason. If client side input panel in im module does not work, fcitx will fallback to a X11 window, instead of a wayland window. The reason for this is because wayland window can not be placed freely on the screen. On the contrary, even if im module can only pass a coordinate relative to the application window to fcitx, which make the coordinate position doesn't make much sense, if your application window size is "maximized", the coordinate may just be "right" if treated as the global coordinate. This makes X11 window a better option than a randomly placed wayland window.

=== KDE Plasma ===
Best setup:
* KDE Plasma 5.27
* Environment variables:
** Set <code>XMODIFIERS=@im=fcitx</code> for XWayland application
** Start fcitx5 by go to "System settings" -> "Virtual keyboard" -> Select Fcitx 5
** Do not set <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> & <code>SDL_IM_MODULE</code> . You could unset <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> by runing <code>im-config</code> and then selecting <code>do not set any IM from im-config and use desktop default"</code>
** Run chromium/electron application with <code>--enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime</code>
* Caveats:
** Certain Gtk/Qt application that only works under X11 may still need to set <code>GTK_IM_MODULE</code> or <code>QT_IM_MODULE</code> for them individually.
** If you set <code>GTK_IM_MODULE/QT_IM_MODULE</code> globally, you will hit this issue [[Special:MyLanguage/FAQ#Candidate_window_is_blinking_under_wayland_with_Fcitx_5|Candidate window is blinking under wayland with Fcitx 5]]

Support Information:
* App/Compositor supports text-input-v2 and text-input-v3.
* Comopositor/Application uses zwp_input_method_v1.
* 5.27 additionally supports text-input-v1.
* 5.24 usable zwp_input_method_v1 with fcitx5. Pre-5.24 there are lots of problems, always use fcitx im module instead.
* Use "Virtual keyboard" KCM to launch fcitx5. This is required to use text-input protocol. If you launch fcitx this way, make sure you do not use "restart" in the tray menu, since the socket passed from KWin can not be reused with the newly restarted fcitx.

=== GNOME ===
Best setup:
* Environment variables:
** Set <code>XMODIFIERS=@im=fcitx</code> for XWayland application
** Set <code>QT_IM_MODULE=fcitx</code> for Qt, since Qt5 would use XWayland by default.
** Run chrome with XWayland and <code>GTK_IM_MODULE=fcitx</code>

Support information:
* Application/Compositor uses text-input-v3
* Compositor/Input Method uses ibus dbus protocol, so ibus frontend is required to be used.
* Adding Fcitx 5 to autostart, it will replace any existing ibus-daemon upon start up so it will work out of box.
* Popup candidate window is not able to be displayed over gnome-shell UI. Only solution is to use [[Special:MyLanguage/Kimpanel|Kimpanel]], [https://extensions.gnome.org/extension/261/kimpanel/ link to extension].
* Qt need to use QT_IM_MODULE=fcitx since there is no text-input-v2 support.

=== Sway ===
* Application/Compositor uses text-input-v3
* Comopositor/Application uses zwp_input_method_v2, but it's partially implemented. You will need [https://github.com/swaywm/sway/pull/7226 this pull request] to make it show the popup candidate window for text-input-v3 client.
* fcitx im module also works.
* Qt need to use QT_IM_MODULE=fcitx since there is no text-input-v2 support.

=== Weston ===
* Application/Compositor uses text-input-v1
* Comopositor/Application uses zwp_input_method_v1.
* Since it has no text-input-v3, which is more commonly used, im module is the only solution for Gtk/Qt, need to set GTK_IM_MODULE=fcitx and QT_IM_MODULE=fcitx.
* Add following content to ~/.config/weston.ini to make it launch fcitx 5. (xwayland part is recommended to make fcitx work best, even if it's wayland)

<pre>
[core]
xwayland=true

[input-method]
path=/usr/bin/fcitx5
</pre>

=== Other compositors ===
Please check their upstream for more information. For wlroots based compositors, it is possible that they also support in the same way as Sway does, or zwp_input_method could also be unsupported.

== Known Issues ==
=== Fcitx managed XKB layout ===
Unlike X11, there is no generic way to set XKB layout to compositor, which means it can only be implemented for every individual desktop. Right now, Fcitx managed layout only works for KDE Plasma and GNOME.

As for other desktop, in order to make this "semi" work you'll need to ensure following:

* The XKB layout of the input method group should be the same as the actual xkb layout you configured for the compositor. Fcitx will "think" the layout is the same and bypass the key conversion logic.
* If you need other layout for text typing (e.g. Arabic), just add them to the Fcitx. As long as the key is forwarded to fcitx, it should work.

=== Popup candidate window ===
Wayland does not have a global coordinate system for regular client, so for native wayland client, it is impossible for Fcitx to place a wayland surface at a certain position. In order for popup window to be placed at the correct position, there are following cases:
* Xwayland have no problem and it should work as good as X11.
* If zwp_input_method protocol can be used, it has a surface role to allow compositor to place the popup window for input method. This only works if client uses text-input protocol.
* For GNOME, kimpanel extension can read window coordinate since it's running inside compositor. As long as im module can report relative coordinate, kimpanel extension can display the popup window at the correct position. As similar approach for Plasma kimpanel is planned, but not yet implemented.
* For Gtk/Qt, fcitx's im module implement a way to render the popup with in the client process. This has some limitation because implemenation of xdg_popup in Gtk3/Qt5 doesn't support reposition the window. So show/hide trick is used to mitigate this, but it may cause window blinking. Fcitx tries not to move window if possible. You may also disable popup animation if you're using KWin to help reduce the blinking.

=== Per-window input method state ===
When zwp_input_method is used, essentially there is only one input context visible to fcitx, and fcitx cannot distinguish what application is being used. Which means the input method "active"/"inactivate" state is now "global".

Now fcitx supports two protocol to figure out the focused window and the corresponding application name, including wlr-foreign-toplevel-management (used by wlroots based compositor) and plasma-window-management (used by kwin).

Using Fcitx 5 on Wayland/en

2025-03-04T11:44:41Z

FuzzyBot: Updating to match new version of source page

<languages />
[https://wayland.freedesktop.org/ Wayland] is the next generation of display server protocol. While the initial release of the protocol is in 2008, the support of input method is not really ideal.

Also, using input method on Wayland-based compositor may require different setup to make it work, and certain features of fcitx that works under X11 are not yet supported by Wayland.

This page will try to cover all the current information with some underlying details, and [[Special:MyLanguage/Setup Fcitx 5|Setup Fcitx 5]] is still generally useful.

== Applications ==
=== TL;DR Do we still need XMODIFIERS, GTK_IM_MODULE and QT_IM_MODULE? ===

==== XMODIFIERS ====
For XMODIFIERS, yes, we do. X11 application running under X11 and XWayland has nearly no difference.

==== GTK_IM_MODULE ====
In an ideal setup, you should use fcitx im module Gtk application running under X11, and Gtk's text-input-v3 for wayland. The way of doing this is:

1. Do NOT set GTK_IM_MODULE environment variable.

2. For Gtk2, Add following content to ~/.gtkrc-2.0

<nowiki>gtk-im-module="fcitx"</nowiki>
3. For Gtk 3, add following content to ~/.config/gtk-3.0/settings.ini

<nowiki>[Settings]
gtk-im-module=fcitx</nowiki>

4. For Gtk 4, add following content to ~/.config/gtk-4.0/settings.ini

<nowiki>[Settings]
gtk-im-module=fcitx</nowiki>

5. If you are using GNOME 3+, also run following command.

<nowiki>gsettings set org.gnome.settings-daemon.plugins.xsettings overrides "{'Gtk/IMModule':<'fcitx'>}"</nowiki>

For GTK_IM_MODULE, as for now, the modern Gtk 3/4 application should be able to use text-input-v3 which is supported almost by every compositor, except weston. There are a few different options in terms of setting the value of GTK_IM_MODULE. When it is unset, the Gtk built-in Wayland im module will be used for Gtk3 and Gtk4. While you can also enforce it by doing GTK_IM_MODULE=wayland, remember it will be also picked up by Gtk2. Setting GTK_IM_MODULE=fcitx can still work, and it is necessary if your compositor does not support Wayland input method frontend.

It is possible to force a certain im module with Gtk configuration file, so without GTK_IM_MODULE set, it will still be able to use different im module.

Per Gtk implementation (still valid for 3.24.41), the order of preferences is:

* X11
** GTK_IM_MODULE in the environment
** Value of Gtk/IMModule from XSettings
** Value from configuration file
** A locale based automatic selection
* Wayland
** GTK_IM_MODULE in the environment
** "wayland"

==== QT_IM_MODULE ====
For QT_IM_MODULE, as for now QT can only use its own text-input-v{2,4}, which is only supported by KWin. Which means, under KDE you should unset it, but under other desktop, you will need to set it to QT_IM_MODULE=fcitx. Also the proprietary Qt applications in the wild complicates the situation. Some do not work on Wayland, some do not bundle/provide Qt wayland. Most of them do not bundle fcitx im module because fcitx is only a third party application to Qt, but I also noticed some do bundle but not bundle all the required libraries. While fcitx 5 support ibus protocol, some of those applications do not even bundle ibus im module. There are a few different environment variables you can try for those proprietary Qt applications (WPS, Anki, DaVinci Resolve, Mathematica, etc...).

<nowiki>QT_IM_MODULE=fcitx # For those who bundle qt im module, e.g. WPS, Anki, you should find a .so file with fcitx in the file name
QT_IM_MODULE=ibus # For those who bundle ibus im module shipped with Qt, you should find libibusplatforminputcontextplugin.so in the package.
QT_QPA_PLATFORM=xcb QT_IM_MODULE=ibus # Enforce it to run on X11/XWayland and use ibus im module
</nowiki>

In Qt 6.7, there is a new environment variable called "QT_IM_MODULES", which allows you so specify a fallback order on im modules. You can set it to

<nowiki>QT_IM_MODULES="wayland;fcitx;ibus"</nowiki>

So it will be able pick up the most usable one even for application that bundles no fcitx/wayland. Remember, you may still need to set( or unset) QT_IM_MODULE (not "QT_IM_MODULES") in order to handle Qt 4/5 applications.

=== Legacy X11 application that runs under XWayland ===
In a word, XWayland support for input method is as good as normal X11 display server. As long as you set the same environment variable, using Xwayland should not be a issue. This category includes:

* Xlib-based (and also other toolkit based on Xlib, e.g. tk, SDL1, etc), e.g. xterm, rxvt. Make sure XMODIFIERS is set correctly.
* Gtk2-based applications, similar to Xlib, but can use fcitx im module. Set GTK_IM_MODULE to fcitx will give it best experience.
* SDL2-based applications that doesn't default to wayland. Set SDL_IM_MODULE to fcitx
* electron, chromium, these are still default to X11, similar to Gtk2 case.
* For Qt4 applcation, Qt 4 can only use X11. You will need to QT_IM_MODULE to fcitx. Same for Qt5+ that uses XCB (can be override with QT_QPA_PLATFORM=xcb).

=== Gtk3 / Gtk4 ===
Gtk3 and Gtk4 support text-input-v3 natively. At the same time, it's also possible to use fcitx im module under wayland. So, either GTK_IM_MODULE=wayland or GTK_IM_MODULE=fcitx works. There are some difference to it. text-input-v3

=== Qt5 / Qt6 ===
If your Qt application natively runs under Wayland, you can either unset QT_IM_MODULE to make it use text-input-v2, or set QT_IM_MODULE=fcitx to make it use fcitx im module.

text-input-v2 is not upstreamed to wayland-protocols, that is probably why only kwin support it. This means in non-kwin environment, you will need to use QT_IM_MODULE=fcitx to make the Qt applications work.

On Qt6, you may also use QT_IM_MODULE= (empty) or QT_IM_MODULE=wayland if your Qt vesion contains this https://codereview.qt-project.org/c/qt/qtwayland/+/416862.

=== Native wayland application (winit) ===
Most likely text-input-v3 is being used.

=== Chromium / Electron ===
{{warning|The information in this section may not be up to date to reflect upstream change, especially the default behavior when no option is changed.}}
TL;DR version, if you use XWayland to run Chromium or Electron application, just install Gtk im module and GTK_IM_MODULE=fcitx the same way like X11.

If you choose to run it natively under Wayland, for chromium you will need to use

# If your compositor supports text-input-v1 protocol. Check the compositor section below.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

# If your compositor & chromium supports text-input-v3 protocol, you may also use
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime --wayland-text-input-version=3

# However, due to a different understanding in text-input-v3 protocol, it has some issue when using with KWin.
# Prefer text-input-v1 if you're using kwin.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime --wayland-text-input-version=1

Or

# You will get wrong position for the input method popup window, unless you use GNOME shell + kimpanel extension.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --gtk-version=4

For electron, only the first option is avaiable (electron does NOT support to run internal chromium with gtk4), e.g. for vscode

# If your compositor supports text-input-v1 protocol. Check the compositor section below.
code --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

By default it should run under Xwayland (As of 2023/02/25 on Archlinux/Chromium 110.0.5481.177), but some user also reports it is using wayland even the "Preferred Ozone Platform" is "Default". So to check whether it's really run with wayland, you can use xeyes or xwininfo. With xeyes, if it's an X11 window, the "eyes" will move with mouse, otherwise it's wayland. With xwininfo, if the mouse cursor changed to "+" shape, and click the window shows the window information, then it is a X11 window.

You may force it to run with Wayland, or X11 with the flag <code>--ozone-platform=wayland</code> and <code>--ozone-platform=x11</code>. You may persistent this by changing the option "Preferred Ozone Platform" in chrome://flags. It has four values, "Default", "X11", "Wayland", "Auto".

It's possible to make it use GTK_IM_MODULE if it runs with Gtk4 (only supported by chromium/chrome at this time, not electron) by passing <code>--gtk-version=4</code>.

It's also possible to make it use text-input-v1 by passing <code>--enable-wayland-ime</code> in addition to the flag above.

The Chromium support for text-input-v1 is not very stable and you may hit some random crash. E.g. in the past, version 112 has a crash bug: https://bugs.chromium.org/p/chromium/issues/detail?id=1431532 , which is fixed in version 115. In the bug comment, Chromium developer claims this text-input-v1 is only supposed to be used internally and not well supported, so use this at your own risk though it's currently the only out of box option.

You should only use one of <code>--enable-wayland-ime</code> or <code>--gtk-version=4</code>, depending on you want to use text-input-v1, or gtk4 im module. text-input-v1 works for kwin 5.27 and weston. Gtk4 im module works on all environment, but only GNOME with Kimpanel extension can display the popup window in the correct position.

== Support in Wayland Compositor ==

Even if you are using only native wayland applications, Xwayland is recommended to be enabled for following reason. If client side input panel in im module does not work, fcitx will fallback to a X11 window, instead of a wayland window. The reason for this is because wayland window can not be placed freely on the screen. On the contrary, even if im module can only pass a coordinate relative to the application window to fcitx, which make the coordinate position doesn't make much sense, if your application window size is "maximized", the coordinate may just be "right" if treated as the global coordinate. This makes X11 window a better option than a randomly placed wayland window.

=== KDE Plasma ===
Best setup:
* KDE Plasma 5.27
* Environment variables:
** Set <code>XMODIFIERS=@im=fcitx</code> for XWayland application
** Start fcitx5 by go to "System settings" -> "Virtual keyboard" -> Select Fcitx 5
** Do not set <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> & <code>SDL_IM_MODULE</code> . You could unset <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> by runing <code>im-config</code> and then selecting <code>do not set any IM from im-config and use desktop default"</code>
** Run chromium/electron application with <code>--enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime</code>
* Caveats:
** Certain Gtk/Qt application that only works under X11 may still need to set <code>GTK_IM_MODULE</code> or <code>QT_IM_MODULE</code> for them individually.
** If you set <code>GTK_IM_MODULE/QT_IM_MODULE</code> globally, you will hit this issue [[Special:MyLanguage/FAQ#Candidate_window_is_blinking_under_wayland_with_Fcitx_5|Candidate window is blinking under wayland with Fcitx 5]]

Support Information:
* App/Compositor supports text-input-v2 and text-input-v3.
* Comopositor/Application uses zwp_input_method_v1.
* 5.27 additionally supports text-input-v1.
* 5.24 usable zwp_input_method_v1 with fcitx5. Pre-5.24 there are lots of problems, always use fcitx im module instead.
* Use "Virtual keyboard" KCM to launch fcitx5. This is required to use text-input protocol. If you launch fcitx this way, make sure you do not use "restart" in the tray menu, since the socket passed from KWin can not be reused with the newly restarted fcitx.

=== GNOME ===
Best setup:
* Environment variables:
** Set <code>XMODIFIERS=@im=fcitx</code> for XWayland application
** Set <code>QT_IM_MODULE=fcitx</code> for Qt, since Qt5 would use XWayland by default.
** Run chrome with XWayland and <code>GTK_IM_MODULE=fcitx</code>

Support information:
* Application/Compositor uses text-input-v3
* Compositor/Input Method uses ibus dbus protocol, so ibus frontend is required to be used.
* Adding Fcitx 5 to autostart, it will replace any existing ibus-daemon upon start up so it will work out of box.
* Popup candidate window is not able to be displayed over gnome-shell UI. Only solution is to use [[Special:MyLanguage/Kimpanel|Kimpanel]], [https://extensions.gnome.org/extension/261/kimpanel/ link to extension].
* Qt need to use QT_IM_MODULE=fcitx since there is no text-input-v2 support.

=== Sway ===
* Application/Compositor uses text-input-v3
* Comopositor/Application uses zwp_input_method_v2, but it's partially implemented. You will need [https://github.com/swaywm/sway/pull/7226 this pull request] to make it show the popup candidate window for text-input-v3 client.
* fcitx im module also works.
* Qt need to use QT_IM_MODULE=fcitx since there is no text-input-v2 support.

=== Weston ===
* Application/Compositor uses text-input-v1
* Comopositor/Application uses zwp_input_method_v1.
* Since it has no text-input-v3, which is more commonly used, im module is the only solution for Gtk/Qt, need to set GTK_IM_MODULE=fcitx and QT_IM_MODULE=fcitx.
* Add following content to ~/.config/weston.ini to make it launch fcitx 5. (xwayland part is recommended to make fcitx work best, even if it's wayland)

<pre>
[core]
xwayland=true

[input-method]
path=/usr/bin/fcitx5
</pre>

=== Other compositors ===
Please check their upstream for more information. For wlroots based compositors, it is possible that they also support in the same way as Sway does, or zwp_input_method could also be unsupported.

== Known Issues ==
=== Fcitx managed XKB layout ===
Unlike X11, there is no generic way to set XKB layout to compositor, which means it can only be implemented for every individual desktop. Right now, Fcitx managed layout only works for KDE Plasma and GNOME.

As for other desktop, in order to make this "semi" work you'll need to ensure following:

* The XKB layout of the input method group should be the same as the actual xkb layout you configured for the compositor. Fcitx will "think" the layout is the same and bypass the key conversion logic.
* If you need other layout for text typing (e.g. Arabic), just add them to the Fcitx. As long as the key is forwarded to fcitx, it should work.

=== Popup candidate window ===
Wayland does not have a global coordinate system for regular client, so for native wayland client, it is impossible for Fcitx to place a wayland surface at a certain position. In order for popup window to be placed at the correct position, there are following cases:
* Xwayland have no problem and it should work as good as X11.
* If zwp_input_method protocol can be used, it has a surface role to allow compositor to place the popup window for input method. This only works if client uses text-input protocol.
* For GNOME, kimpanel extension can read window coordinate since it's running inside compositor. As long as im module can report relative coordinate, kimpanel extension can display the popup window at the correct position. As similar approach for Plasma kimpanel is planned, but not yet implemented.
* For Gtk/Qt, fcitx's im module implement a way to render the popup with in the client process. This has some limitation because implemenation of xdg_popup in Gtk3/Qt5 doesn't support reposition the window. So show/hide trick is used to mitigate this, but it may cause window blinking. Fcitx tries not to move window if possible. You may also disable popup animation if you're using KWin to help reduce the blinking.

=== Per-window input method state ===
When zwp_input_method is used, essentially there is only one input context visible to fcitx, and fcitx cannot distinguish what application is being used. Which means the input method "active"/"inactivate" state is now "global".

Now fcitx supports two protocol to figure out the focused window and the corresponding application name, including wlr-foreign-toplevel-management (used by wlroots based compositor) and plasma-window-management (used by kwin).

Translations:Using Fcitx 5 on Wayland/62/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

Now fcitx supports two protocol to figure out the focused window and the corresponding application name, including wlr-foreign-toplevel-management (used by wlroots based compositor) and plasma-window-management (used by kwin).

Translations:Using Fcitx 5 on Wayland/61/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

=== Per-window input method state ===
When zwp_input_method is used, essentially there is only one input context visible to fcitx, and fcitx cannot distinguish what application is being used. Which means the input method "active"/"inactivate" state is now "global".

Translations:Using Fcitx 5 on Wayland/60/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

=== Popup candidate window ===
Wayland does not have a global coordinate system for regular client, so for native wayland client, it is impossible for Fcitx to place a wayland surface at a certain position. In order for popup window to be placed at the correct position, there are following cases:
* Xwayland have no problem and it should work as good as X11.
* If zwp_input_method protocol can be used, it has a surface role to allow compositor to place the popup window for input method. This only works if client uses text-input protocol.
* For GNOME, kimpanel extension can read window coordinate since it's running inside compositor. As long as im module can report relative coordinate, kimpanel extension can display the popup window at the correct position. As similar approach for Plasma kimpanel is planned, but not yet implemented.
* For Gtk/Qt, fcitx's im module implement a way to render the popup with in the client process. This has some limitation because implemenation of xdg_popup in Gtk3/Qt5 doesn't support reposition the window. So show/hide trick is used to mitigate this, but it may cause window blinking. Fcitx tries not to move window if possible. You may also disable popup animation if you're using KWin to help reduce the blinking.

Translations:Using Fcitx 5 on Wayland/59/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

* The XKB layout of the input method group should be the same as the actual xkb layout you configured for the compositor. Fcitx will "think" the layout is the same and bypass the key conversion logic.
* If you need other layout for text typing (e.g. Arabic), just add them to the Fcitx. As long as the key is forwarded to fcitx, it should work.

Translations:Using Fcitx 5 on Wayland/58/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

As for other desktop, in order to make this "semi" work you'll need to ensure following:

Translations:Using Fcitx 5 on Wayland/57/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

== Known Issues ==
=== Fcitx managed XKB layout ===
Unlike X11, there is no generic way to set XKB layout to compositor, which means it can only be implemented for every individual desktop. Right now, Fcitx managed layout only works for KDE Plasma and GNOME.

Translations:Using Fcitx 5 on Wayland/56/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

=== Other compositors ===
Please check their upstream for more information. For wlroots based compositors, it is possible that they also support in the same way as Sway does, or zwp_input_method could also be unsupported.

Translations:Using Fcitx 5 on Wayland/55/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

[input-method]
path=/usr/bin/fcitx5
</pre>

Translations:Using Fcitx 5 on Wayland/54/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

<pre>
[core]
xwayland=true

Translations:Using Fcitx 5 on Wayland/53/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

=== Weston ===
* Application/Compositor uses text-input-v1
* Comopositor/Application uses zwp_input_method_v1.
* Since it has no text-input-v3, which is more commonly used, im module is the only solution for Gtk/Qt, need to set GTK_IM_MODULE=fcitx and QT_IM_MODULE=fcitx.
* Add following content to ~/.config/weston.ini to make it launch fcitx 5. (xwayland part is recommended to make fcitx work best, even if it's wayland)

Translations:Using Fcitx 5 on Wayland/52/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

=== Sway ===
* Application/Compositor uses text-input-v3
* Comopositor/Application uses zwp_input_method_v2, but it's partially implemented. You will need [https://github.com/swaywm/sway/pull/7226 this pull request] to make it show the popup candidate window for text-input-v3 client.
* fcitx im module also works.
* Qt need to use QT_IM_MODULE=fcitx since there is no text-input-v2 support.

Translations:Using Fcitx 5 on Wayland/51/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

Support information:
* Application/Compositor uses text-input-v3
* Compositor/Input Method uses ibus dbus protocol, so ibus frontend is required to be used.
* Adding Fcitx 5 to autostart, it will replace any existing ibus-daemon upon start up so it will work out of box.
* Popup candidate window is not able to be displayed over gnome-shell UI. Only solution is to use [[Special:MyLanguage/Kimpanel|Kimpanel]], [https://extensions.gnome.org/extension/261/kimpanel/ link to extension].
* Qt need to use QT_IM_MODULE=fcitx since there is no text-input-v2 support.

Translations:Using Fcitx 5 on Wayland/50/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

=== GNOME ===
Best setup:
* Environment variables:
** Set <code>XMODIFIERS=@im=fcitx</code> for XWayland application
** Set <code>QT_IM_MODULE=fcitx</code> for Qt, since Qt5 would use XWayland by default.
** Run chrome with XWayland and <code>GTK_IM_MODULE=fcitx</code>

Translations:Using Fcitx 5 on Wayland/49/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

Support Information:
* App/Compositor supports text-input-v2 and text-input-v3.
* Comopositor/Application uses zwp_input_method_v1.
* 5.27 additionally supports text-input-v1.
* 5.24 usable zwp_input_method_v1 with fcitx5. Pre-5.24 there are lots of problems, always use fcitx im module instead.
* Use "Virtual keyboard" KCM to launch fcitx5. This is required to use text-input protocol. If you launch fcitx this way, make sure you do not use "restart" in the tray menu, since the socket passed from KWin can not be reused with the newly restarted fcitx.

Translations:Using Fcitx 5 on Wayland/48/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

=== KDE Plasma ===
Best setup:
* KDE Plasma 5.27
* Environment variables:
** Set <code>XMODIFIERS=@im=fcitx</code> for XWayland application
** Start fcitx5 by go to "System settings" -> "Virtual keyboard" -> Select Fcitx 5
** Do not set <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> & <code>SDL_IM_MODULE</code> . You could unset <code>GTK_IM_MODULE</code> & <code>QT_IM_MODULE</code> by runing <code>im-config</code> and then selecting <code>do not set any IM from im-config and use desktop default"</code>
** Run chromium/electron application with <code>--enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime</code>
* Caveats:
** Certain Gtk/Qt application that only works under X11 may still need to set <code>GTK_IM_MODULE</code> or <code>QT_IM_MODULE</code> for them individually.
** If you set <code>GTK_IM_MODULE/QT_IM_MODULE</code> globally, you will hit this issue [[Special:MyLanguage/FAQ#Candidate_window_is_blinking_under_wayland_with_Fcitx_5|Candidate window is blinking under wayland with Fcitx 5]]

Translations:Using Fcitx 5 on Wayland/47/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

Even if you are using only native wayland applications, Xwayland is recommended to be enabled for following reason. If client side input panel in im module does not work, fcitx will fallback to a X11 window, instead of a wayland window. The reason for this is because wayland window can not be placed freely on the screen. On the contrary, even if im module can only pass a coordinate relative to the application window to fcitx, which make the coordinate position doesn't make much sense, if your application window size is "maximized", the coordinate may just be "right" if treated as the global coordinate. This makes X11 window a better option than a randomly placed wayland window.

Translations:Using Fcitx 5 on Wayland/46/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

== Support in Wayland Compositor ==

Translations:Using Fcitx 5 on Wayland/45/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

You should only use one of <code>--enable-wayland-ime</code> or <code>--gtk-version=4</code>, depending on you want to use text-input-v1, or gtk4 im module. text-input-v1 works for kwin 5.27 and weston. Gtk4 im module works on all environment, but only GNOME with Kimpanel extension can display the popup window in the correct position.

Translations:Using Fcitx 5 on Wayland/44/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

The Chromium support for text-input-v1 is not very stable and you may hit some random crash. E.g. in the past, version 112 has a crash bug: https://bugs.chromium.org/p/chromium/issues/detail?id=1431532 , which is fixed in version 115. In the bug comment, Chromium developer claims this text-input-v1 is only supposed to be used internally and not well supported, so use this at your own risk though it's currently the only out of box option.

Translations:Using Fcitx 5 on Wayland/43/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

It's also possible to make it use text-input-v1 by passing <code>--enable-wayland-ime</code> in addition to the flag above.

Translations:Using Fcitx 5 on Wayland/42/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

It's possible to make it use GTK_IM_MODULE if it runs with Gtk4 (only supported by chromium/chrome at this time, not electron) by passing <code>--gtk-version=4</code>.

Translations:Using Fcitx 5 on Wayland/41/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

You may force it to run with Wayland, or X11 with the flag <code>--ozone-platform=wayland</code> and <code>--ozone-platform=x11</code>. You may persistent this by changing the option "Preferred Ozone Platform" in chrome://flags. It has four values, "Default", "X11", "Wayland", "Auto".

Translations:Using Fcitx 5 on Wayland/40/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

By default it should run under Xwayland (As of 2023/02/25 on Archlinux/Chromium 110.0.5481.177), but some user also reports it is using wayland even the "Preferred Ozone Platform" is "Default". So to check whether it's really run with wayland, you can use xeyes or xwininfo. With xeyes, if it's an X11 window, the "eyes" will move with mouse, otherwise it's wayland. With xwininfo, if the mouse cursor changed to "+" shape, and click the window shows the window information, then it is a X11 window.

Translations:Using Fcitx 5 on Wayland/39/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

# If your compositor supports text-input-v1 protocol. Check the compositor section below.
code --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

Translations:Using Fcitx 5 on Wayland/38/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

For electron, only the first option is avaiable (electron does NOT support to run internal chromium with gtk4), e.g. for vscode

Translations:Using Fcitx 5 on Wayland/37/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

# You will get wrong position for the input method popup window, unless you use GNOME shell + kimpanel extension.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --gtk-version=4

Translations:Using Fcitx 5 on Wayland/36/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

Translations:Using Fcitx 5 on Wayland/35/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

# However, due to a different understanding in text-input-v3 protocol, it has some issue when using with KWin.
# Prefer text-input-v1 if you're using kwin.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime --wayland-text-input-version=1

Translations:Using Fcitx 5 on Wayland/34/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

# If your compositor & chromium supports text-input-v3 protocol, you may also use
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime --wayland-text-input-version=3

Translations:Using Fcitx 5 on Wayland/33/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

# If your compositor supports text-input-v1 protocol. Check the compositor section below.
chromium --enable-features=UseOzonePlatform --ozone-platform=wayland --enable-wayland-ime

Translations:Using Fcitx 5 on Wayland/32/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

If you choose to run it natively under Wayland, for chromium you will need to use

Translations:Using Fcitx 5 on Wayland/31/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

=== Chromium / Electron ===
{{warning|The information in this section may not be up to date to reflect upstream change, especially the default behavior when no option is changed.}}
TL;DR version, if you use XWayland to run Chromium or Electron application, just install Gtk im module and GTK_IM_MODULE=fcitx the same way like X11.

Translations:Using Fcitx 5 on Wayland/30/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

=== Native wayland application (winit) ===
Most likely text-input-v3 is being used.

Translations:Using Fcitx 5 on Wayland/29/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

On Qt6, you may also use QT_IM_MODULE= (empty) or QT_IM_MODULE=wayland if your Qt vesion contains this https://codereview.qt-project.org/c/qt/qtwayland/+/416862.

Translations:Using Fcitx 5 on Wayland/28/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

text-input-v2 is not upstreamed to wayland-protocols, that is probably why only kwin support it. This means in non-kwin environment, you will need to use QT_IM_MODULE=fcitx to make the Qt applications work.

Translations:Using Fcitx 5 on Wayland/27/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

=== Qt5 / Qt6 ===
If your Qt application natively runs under Wayland, you can either unset QT_IM_MODULE to make it use text-input-v2, or set QT_IM_MODULE=fcitx to make it use fcitx im module.

Translations:Using Fcitx 5 on Wayland/26/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

=== Gtk3 / Gtk4 ===
Gtk3 and Gtk4 support text-input-v3 natively. At the same time, it's also possible to use fcitx im module under wayland. So, either GTK_IM_MODULE=wayland or GTK_IM_MODULE=fcitx works. There are some difference to it. text-input-v3

Translations:Using Fcitx 5 on Wayland/25/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

* Xlib-based (and also other toolkit based on Xlib, e.g. tk, SDL1, etc), e.g. xterm, rxvt. Make sure XMODIFIERS is set correctly.
* Gtk2-based applications, similar to Xlib, but can use fcitx im module. Set GTK_IM_MODULE to fcitx will give it best experience.
* SDL2-based applications that doesn't default to wayland. Set SDL_IM_MODULE to fcitx
* electron, chromium, these are still default to X11, similar to Gtk2 case.
* For Qt4 applcation, Qt 4 can only use X11. You will need to QT_IM_MODULE to fcitx. Same for Qt5+ that uses XCB (can be override with QT_QPA_PLATFORM=xcb).

Translations:Using Fcitx 5 on Wayland/24/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

=== Legacy X11 application that runs under XWayland ===
In a word, XWayland support for input method is as good as normal X11 display server. As long as you set the same environment variable, using Xwayland should not be a issue. This category includes:

Translations:Using Fcitx 5 on Wayland/23/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

So it will be able pick up the most usable one even for application that bundles no fcitx/wayland. Remember, you may still need to set( or unset) QT_IM_MODULE (not "QT_IM_MODULES") in order to handle Qt 4/5 applications.

Translations:Using Fcitx 5 on Wayland/22/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

<nowiki>QT_IM_MODULES="wayland;fcitx;ibus"</nowiki>

Translations:Using Fcitx 5 on Wayland/21/en

2025-03-04T11:44:39Z

FuzzyBot: Importing a new version from external source

In Qt 6.7, there is a new environment variable called "QT_IM_MODULES", which allows you so specify a fallback order on im modules. You can set it to