Inspect and Simplify GTK .ui Files Safely

gtk-builder-tool checks a GTK 3 GtkBuilder file, lists its objects, previews one of them and can shrink the XML, all without risking the original. Allow about 15 minutes for a first pass, plus time to test the result in the application that owns it.

This guide covers the gtk-builder-tool shipped by Ubuntu's libgtk-3-bin package. The installed package here is version 3.24.41-4ubuntu1.3. The manual page is dated 27 January 2025, so keep the command output below tied to this installed GTK 3 build rather than assuming identical details on another release.

1. Check the command and prepare a copy

Start with a readable .ui file and confirm which executable will run. Neither check needs elevated privileges.

$ command -v gtk-builder-tool
/usr/bin/gtk-builder-tool
$ dpkg-query -W -f='${Package} ${Version}\n' libgtk-3-bin
libgtk-3-bin 3.24.41-4ubuntu1.3

Make a working copy before using any command that can write the file. Replace the two placeholder paths with your own locations:

$ cp --preserve=all /path/to/main.ui /path/to/main.ui.before-builder-tool
$ test -r /path/to/main.ui && echo "input is readable"
input is readable

Recovery: keep the copy until the application has loaded the result successfully. It is your undo path if simplification removes something the application relies on.

2. Validate the XML and GTK objects

Run validate before making any change. It reports errors on standard error and returns a non-zero status when it cannot open or parse the file. The tool initialises GTK, so a graphical display is required even for this non-interactive check.

$ gtk-builder-tool validate /path/to/main.ui
$ printf 'exit status: %s\n' "$?"
exit status: 0

On a headless machine, provide a temporary X display if xvfb-run is installed:

$ xvfb-run -a gtk-builder-tool validate /path/to/main.ui
$ printf 'exit status: %s\n' "$?"
exit status: 0

No output and status 0 mean this tool accepted the file. They do not prove your application will behave correctly: application code, signal handlers, resources and runtime data are outside this check. If the path is wrong, expect an error such as Failed to open file ...: No such file or directory and status 1.

3. List the named objects

Use enumerate to see the IDs the file creates, one ID and its GTK class per line:

$ xvfb-run -a gtk-builder-tool enumerate /path/to/main.ui
main_window (GtkWindow)
ok_button (GtkButton)

The exact list comes from your file. IDs are useful when checking a refactor, choosing a preview target, or comparing two revisions. An object without a useful ID is harder for application code to retrieve with gtk_builder_get_object(), but adding IDs is an XML and application change, not something this command repairs.

4. Preview one object

preview opens a GTK window for a suitable object chosen by the tool. Select one explicitly when the file contains several widgets:

$ gtk-builder-tool preview --id=ok_button /path/to/main.ui

Leave the command running while you inspect the window, then close the preview normally. The optional --css=FILE argument loads style information from a CSS file:

$ gtk-builder-tool preview --id=ok_button --css=/path/to/test.css /path/to/main.ui

Preview is a visual inspection aid, not an application test: it may not provide the application context, signal connections, resources or data the real program supplies. A preview also needs a working display, so on a remote system check your X or Wayland forwarding before diagnosing the UI file.

5. Generate a simplified file without replacing the original

simplify removes properties set to their default values and writes the resulting XML to standard output by default. Redirect it to a new file, never directly over the source:

$ gtk-builder-tool simplify /path/to/main.ui > /path/to/main.ui.simplified
$ test -s /path/to/main.ui.simplified && echo "simplified file is non-empty"
simplified file is non-empty
$ xvfb-run -a gtk-builder-tool validate /path/to/main.ui.simplified
$ printf 'exit status: %s\n' "$?"
exit status: 0

Keeping output separate matters because shell redirection creates or truncates the destination before the command starts. If simplification fails, the original stays intact and you can remove the incomplete new file after checking the failure:

$ rm /path/to/main.ui.simplified

Destructive action: that rm only touches the named output, so do not substitute the source path. There is normally no reason to use sudo; write in a directory you own.

6. Replace the file only after testing

Once the separate file validates and your application has been tested against it, replace the original in a controlled step. First preserve the existing file if you have not already:

$ cp --preserve=all /path/to/main.ui /path/to/main.ui.before-builder-tool
$ mv /path/to/main.ui.simplified /path/to/main.ui
$ xvfb-run -a gtk-builder-tool validate /path/to/main.ui

mv changes the filename immediately. If the application now fails to start or a widget is missing, stop the affected test service or application before further edits, then restore the backup:

$ cp --preserve=all /path/to/main.ui.before-builder-tool /path/to/main.ui
$ xvfb-run -a gtk-builder-tool validate /path/to/main.ui

Warning: do not run this replacement against a system package file or a live service without that service owner's normal maintenance and rollback process. A valid XML file can still change visual defaults or behaviour when application code depended on an explicit property.

Common traps

Done means