Regenerate GTK 3 Input Method Modules Safely

Use gtk-query-immodules-3.0 to build a verified GTK 3 input method cache, or a disposable one you can test before ever touching the system copy. The examples use GTK 3.24.41 from the installed libgtk-3-bin version 3.24.41-4ubuntu1.3 and its matching runtime helper.

The route

Jump straight to the step you need, or tick off Done means at the end.

1. Find the helper and inspect the current cache
2. Generate a disposable cache on standard output
3. Query one known module
4. Update the default system cache
5. Check the result after an update

Allow about ten minutes. You need a shell and, if you are testing a particular module, an input method module already installed. The ordinary inspection commands need no elevated privileges. Updating the system cache does change a file used by GTK applications, so this guide keeps that step explicit.

1. Find the helper and inspect the current cache

Start by locating the executable and the cache. Do not assume the helper is on PATH: on this installation the manpage is supplied by libgtk-3-bin, while the executable lives under the GTK runtime directory.

$ command -v gtk-query-immodules-3.0 || true
$ find /usr -type f -name 'gtk-query-immodules-3.0' -perm -111 2>/dev/null
/usr/lib/x86_64-linux-gnu/libgtk-3-0t64/gtk-query-immodules-3.0
$ find /usr/lib -type f -name immodules.cache 2>/dev/null
/usr/lib/x86_64-linux-gnu/gtk-3.0/3.0.0/immodules.cache

Set a shell variable to the path found on your machine. The placeholder below is the path verified here; replace it if your architecture or package layout differs:

QUERY='/usr/lib/x86_64-linux-gnu/libgtk-3-0t64/gtk-query-immodules-3.0'
test -x "$QUERY" && printf '%s\n' 'helper is executable'

Checkpoint

The final line should say helper is executable. If it does not, stop and use the path printed by find.

2. Generate a disposable cache on standard output

With no module arguments, the utility searches the GTK input method module path and writes the generated cache to standard output. Redirect it to a file in /tmp so you can inspect it without touching the system cache:

$ TMP_CACHE=$(mktemp /tmp/gtk-immodules.XXXXXX)
$ "$QUERY" >"$TMP_CACHE"
$ printf 'status=%s, lines=%s\n' "$?" "$(wc -l <"$TMP_CACHE")"
status=0, lines=46
$ sed -n '1,8p' "$TMP_CACHE"
# GTK+ Input Method Modules file
# Automatically generated file, do not edit
# Created by /usr/lib/x86_64-linux-gnu/libgtk-3-0t64/gtk-query-immodules-3.0 from gtk+-3.24.41

The line count is host-specific. What matters is exit status 0, the generated-file header, and module records containing absolute shared-library paths. Standard output here is the cache data, not a progress report.

To make one GTK 3 process use this disposable file, set GTK_IM_MODULE_FILE only for that process:

GTK_IM_MODULE_FILE="$TMP_CACHE" your-gtk3-program

Tip

The environment variable is deliberately scoped to one command. Do not export it globally unless you intend every GTK application to use that exact file. GTK 2.x also reads the variable, and a GTK 3 cache is not a safe system-wide setting for both generations.

3. Query one known module

Arguments are module paths, either absolute or relative. Testing one installed module separates module discovery from cache installation:

$ MODULE='/usr/lib/x86_64-linux-gnu/gtk-3.0/3.0.0/immodules/im-xim.so'
$ "$QUERY" "$MODULE"
# GTK+ Input Method Modules file
# Automatically generated file, do not edit
# Created by /usr/lib/x86_64-linux-gnu/libgtk-3-0t64/gtk-query-immodules-3.0 from gtk+-3.24.41
#
"/usr/lib/x86_64-linux-gnu/gtk-3.0/3.0.0/immodules/im-xim.so"
"xim" "X Input Method" "gtk30" "/usr/share/locale" "ko:ja:th:zh"

Your module's path and metadata will differ. A successful record shows the shared object exposes the GTK input method module API. Keep the module path quoted: paths supplied by a package normally contain no spaces, but quoting avoids turning a path into several arguments.

Checkpoint

Try a deliberately missing path only when diagnosing a failure:

$ "$QUERY" /tmp/does-not-exist.so >/tmp/gtk-invalid.out 2>/tmp/gtk-invalid.err
$ printf 'status=%s\n' "$?"
status=1
$ sed -n '1,2p' /tmp/gtk-invalid.err
Cannot load module /tmp/does-not-exist.so: ... cannot open shared object file

Status 1 means the requested module could not be loaded in this test. It does not prove GTK itself is broken. Check the path, architecture and shared-library dependencies before changing the cache.

4. Update the default system cache

Only do this once the disposable output looks sensible and you have installed or changed an input method module. The documented --update-cache option writes to the default location, normally libdir/gtk-3.0/3.0.0/immodules.cache:

$ sudo "$QUERY" --update-cache
$ printf 'status=%s\n' "$?"
status=0

Warning

This is the one state-changing command in the guide. It may replace the cache used by running or newly started GTK applications, and it normally requires elevated privileges because the default file is under /usr/lib. Do not run it merely to inspect output, and do not use a guessed module path with this option.

Recovery

There is no command-specific undo. Recover by regenerating the cache again from the currently installed module set, or by restoring the package's cache through your system's package-management process. If the update fails, leave the existing cache in place and investigate the error; do not hand-edit a replacement.

5. Check the result after an update

Confirm the default cache exists and that its header names the GTK version used to generate it:

$ CACHE='/usr/lib/x86_64-linux-gnu/gtk-3.0/3.0.0/immodules.cache'
$ test -s "$CACHE" && sed -n '1,4p' "$CACHE"
# GTK+ Input Method Modules file
# Automatically generated file, do not edit
# Created by ... from gtk+-3.24.41

If a newly installed module is absent, first check that it sits in the directory GTK searches, or regenerate from an explicit path. The GTK_PATH environment variable prepends directories to that search path, which can be useful for a controlled test but can also make an unrelated module set win. Keep temporary GTK_PATH assignments on the command that needs them.

Remove only the disposable files made by this guide when you have finished:

rm -f -- "$TMP_CACHE" /tmp/gtk-invalid.out /tmp/gtk-invalid.err

Done means

Helper found. The helper path was found and executed successfully.
Disposable cache built. A no-argument run produced cache data on standard output with status 0.
Module checked. A representative module produced a metadata record, or its failure was diagnosed from the error and status.
System cache updated deliberately. --update-cache was used only when a system-wide cache change was actually required.
Result confirmed. The default cache exists and identifies the expected GTK 3 version.