Convert Glade Files to GtkBuilder XML

Use gtk-builder-convert to turn a legacy Glade file into XML that GtkBuilder can load, without touching the original file. Along the way you will learn to omit top-level windows, pull out one widget subtree, and send the result to standard output. Allow about fifteen minutes including a quick inspection of the generated XML.

This guide describes the command installed from Debian package libgtk2.0-dev:amd64, version 2.24.33-4ubuntu1.1, on this machine. The installed script is /usr/bin/gtk-builder-convert and requires Python 3. No elevated privileges are needed when reading a project in your home directory and writing the converted file there.

1. Check the installed interface

Confirm which executable your shell will run and read its local help. This is a read-only checkpoint:

$ command -v gtk-builder-convert
/usr/bin/gtk-builder-convert
$ gtk-builder-convert --help
Usage: gtk-builder-convert [OPTION] [INPUT] [OUTPUT]
Converts Glade files into XML files which can be loaded with GtkBuilder.
...
When OUTPUT is -, write to standard output.

The useful shape is gtk-builder-convert [OPTION] INPUT OUTPUT: input first, output second.

Tip: treat the help text as authoritative for this installed program. The packaged manpage also documents --target-version, but this 2.24.33 script does not list or accept that option.

2. Convert to a new file

Choose an output name that does not clash with the original Glade file. This example uses obvious placeholders; replace both paths with files in your project:

$ gtk-builder-convert /path/to/project.glade /path/to/project.ui
Wrote /path/to/project.ui

A successful run prints a Wrote message and exits with status zero. The converter writes the destination but does not edit the input. Check both the status and the beginning of the result:

$ test -s /path/to/project.ui && head -n 8 /path/to/project.ui
<?xml version="1.0"?>
<!--*- mode: xml -*-->
<interface>
  <object class="GtkWindow" id="MainWindow">
    ...

The exact objects, properties and identifiers depend on your Glade file. Seeing an XML declaration and an interface root is a useful format check, not proof that every widget is supported by the GTK version that will load it.

3. Avoid clobbering an existing conversion

The destination is a normal output path. If it already exists, the script opens it for writing and can replace it. Check first when the file matters:

$ test ! -e /path/to/project.ui || { echo "refusing to replace existing output"; exit 1; }
$ gtk-builder-convert /path/to/project.glade /path/to/project.ui

If you need to replace an existing result, preserve it before converting. This changes state, so the backup is your recovery point:

$ cp --preserve=all /path/to/project.ui /path/to/project.ui.bak
$ gtk-builder-convert /path/to/project.glade /path/to/project.ui

Recovery: keep the .bak until the new XML has been reviewed and loaded by your application. To undo the replacement, restore it explicitly with cp --preserve=all /path/to/project.ui.bak /path/to/project.ui. Do not remove the backup as part of a blind script.

4. Convert only a widget subtree

Use --root, or its short form -r, when you need one named widget and its children rather than the whole file. The name must match the widget's Glade identifier:

$ gtk-builder-convert --root MainWindow /path/to/project.glade /path/to/window.ui
Wrote /path/to/window.ui

Inspect the output to confirm the expected identifier is present:

$ grep -n 'id="MainWindow"' /path/to/window.ui
4:  <object class="GtkWindow" id="MainWindow">

If the name is wrong, conversion can fail or produce no useful subtree. Do not guess an identifier from the filename: search the source first with grep -n 'id=' /path/to/project.glade, then repeat the command with the exact value.

5. Omit windows or capture standard output

--skip-windows, also written -w, converts everything except GtkWindow subclasses. Useful when a library or test needs the child widgets without top-level windows:

$ gtk-builder-convert --skip-windows /path/to/project.glade /path/to/widgets.ui
Wrote /path/to/widgets.ui
$ grep -n 'GtkWindow' /path/to/widgets.ui || echo "no GtkWindow objects found"

Do not assume this option makes a complete application file: removing windows can also remove the object that gave the original interface its top-level structure. Treat the output as a selected conversion and test it with the consumer that will load it.

For a review, pipeline, or temporary result, use - as the output name. Redirect standard output to a new file and keep diagnostics visible:

$ gtk-builder-convert /path/to/project.glade - > /path/to/review.ui
$ test -s /path/to/review.ui && head -n 5 /path/to/review.ui

A redirection target is still truncated before the program starts, so use the same existence check or backup pattern when the destination is valuable.

6. Handle failures without changing the source

Conversion errors usually point to an unreadable input, an invalid option, or a Glade construct the script cannot translate. Check the path and permissions without reaching for sudo:

$ ls -l /path/to/project.glade
$ gtk-builder-convert --help

The tool's documented limitations include unsupported toolbars and no implemented accessibility support. A zero exit status means the script completed its conversion; it does not certify that the resulting interface meets your application's accessibility or widget compatibility needs. Load the generated file in the actual GTK application, and keep the original Glade file until that test passes.

For this package, use -h or --help for the available options. Do not copy --target-version from the manpage into an automated build without testing the installed binary first: if a newer package adds that switch, its accepted values and conversion rules may differ.

Done means