Rebuild the GIO Module Cache Safely with gio-querymodules

You will rebuild the giomodule.cache file that GIO uses to discover extension points without opening every module at application start-up. This is useful after installing or replacing GIO modules. The examples use the Ubuntu package libglib2.0-bin, version 2.80.0-6ubuntu3.9, and the installed binary at /usr/bin/gio-querymodules.

Allow about ten minutes. You need a shell, a directory containing GIO module shared libraries, and permission to write that directory. The command changes one generated cache file. It does not install modules, alter the libraries, or enable a module that is not already present.

1. Confirm the command and target directory

Start with read-only checks. GIO modules are normally placed in a gio/modules directory below the system library directory, but the exact path varies by distribution and architecture:

$ command -v gio-querymodules
/usr/bin/gio-querymodules
$ dpkg-query -W -f='${Package} ${Version}\n' libglib2.0-bin
libglib2.0-bin 2.80.0-6ubuntu3.9
$ find /usr/lib /usr/lib64 -type d -path '*/gio/modules' -print 2>/dev/null
/usr/lib/x86_64-linux-gnu/gio/modules

Your output can contain a different architecture path, or more than one module directory. Use the directory that owns the modules used by the GIO installation you are repairing. Do not pass the parent lib directory just because it is shorter.

$ find /path/to/gio/modules -maxdepth 1 -type f -name '*.so' -printf '%f\n' | sort
$ ls -l /path/to/gio/modules/giomodule.cache

If the cache does not exist, ls will report that fact. That is not a problem. The important checks are that the directory is the one you intended and that it contains the module files you expect.

2. Check the cache operation in a disposable directory

Before touching a system directory, test the command with copies of the installed modules. This needs no elevated privilege and leaves the originals alone:

$ test_dir=$(mktemp -d /tmp/gio-querymodules-XXXXXX)
$ cp /usr/lib/x86_64-linux-gnu/gio/modules/*.so "$test_dir" 
$ /usr/bin/gio-querymodules "$test_dir"
$ ls -l "$test_dir/giomodule.cache"
-rw-r--r-- 1 user user 150 Sep 24 00:50 /tmp/gio-querymodules-ABC123/giomodule.cache
$ cat "$test_dir/giomodule.cache"
libdconfsettings.so: gsettings-backend
libgiognomeproxy.so: gio-proxy-resolver
libgiognutls.so: gio-tls-backend
libgiolibproxy.so: gio-proxy-resolver

The filenames and timestamps will differ. The useful result is a cache file containing module names and the extension points returned by those modules. An empty directory does not produce a useful cache on this installed version, so do not treat a missing cache in an empty test directory as a successful module discovery test.

When you have finished inspecting the disposable directory, remove it with rm -rf -- "$test_dir". This is safe only because test_dir came directly from mktemp and is an explicitly named temporary directory. Never substitute a system path in that command.

3. Rebuild the real cache

Run the command as the account that owns the module directory. Writing a cache below /usr/lib normally requires elevated privileges:

$ sudo /usr/bin/gio-querymodules /usr/lib/x86_64-linux-gnu/gio/modules
$ ls -l /usr/lib/x86_64-linux-gnu/gio/modules/giomodule.cache
-rw-r--r-- 1 root root ... /usr/lib/x86_64-linux-gnu/gio/modules/giomodule.cache

Replace the path with the directory you confirmed in step 1. The command accepts one or more directories, so a multi-directory rebuild can be written as:

$ sudo /usr/bin/gio-querymodules \
    /path/to/first/gio/modules \
    /path/to/second/gio/modules

Each listed directory is handled independently. The output file is named giomodule.cache inside that directory. There are no documented flags to select another output name, inspect the cache, or perform a dry run.

4. Verify the result and the modules GIO can see

Check that the cache is present, owned appropriately, and non-empty:

$ stat --format='mode=%A owner=%U:%G size=%s path=%n' \
    /usr/lib/x86_64-linux-gnu/gio/modules/giomodule.cache
mode=-rw-r--r-- owner=root:root size=150 path=/usr/lib/x86_64-linux-gnu/gio/modules/giomodule.cache
$ sed -n '1,20p' /usr/lib/x86_64-linux-gnu/gio/modules/giomodule.cache
libdconfsettings.so: gsettings-backend
libgiognomeproxy.so: gio-proxy-resolver
libgiognutls.so: gio-tls-backend
libgiolibproxy.so: gio-proxy-resolver

The exact size, ownership and lines depend on the modules installed on your machine. A cache line records an extension point reported by a module; it is not a complete health check for that module. If a module was copied into the directory but does not implement the query interface, it may not appear in the cache even though the shared library exists.

For a non-standard module directory, GIO can use GIO_EXTRA_MODULES as a colon-separated list of additional directories. That environment variable affects where GIO looks, but it does not create a cache. Run gio-querymodules against each additional directory after installing its modules.

5. Diagnose failures without guessing

If the command prints an error such as Unable to open directory, check the path and permissions:

$ name='/path/to/gio/modules'
$ test -d "$name" && echo 'directory exists'
$ test -r "$name" && echo 'directory is readable'
$ test -w "$name" && echo 'directory is writable'
$ find "$name" -maxdepth 1 -type f -name '*.so' -print

Run the command with sudo only when the intended directory is valid and the failure is a write-permission problem. Do not use elevated privileges to compensate for a misspelled path. In this installed version, an unreadable or missing directory can print an error while still returning shell status 0, so inspect the diagnostic and verify the resulting cache rather than relying on $? alone.

If applications still do not load a module, first compare the module directory with the directory GIO is actually configured to use. Check for a stale package installation, a wrong architecture, or a module whose dependencies cannot be loaded. Rebuilding the cache cannot repair a broken shared library. If you replaced a cache and need to recover, rerun the command after restoring the intended module set. The cache is generated data, so do not hand-edit it.