Pre-render GTK Symbolic SVGs as Faster PNGs

Use gtk-encode-symbolic-svg to turn a GTK symbolic SVG into a PNG at an explicit size, ready for the same GTK icon-loading path but faster. The output keeps the .symbolic.png suffix, so it stays distinguishable from an ordinary PNG.

Allow about ten minutes. You need the gtk-encode-symbolic-svg command from the libgtk-3-bin package, a symbolic SVG you are allowed to read, and a writable output directory. The examples use GTK+ package version 3.24.41-4ubuntu1.3, installed on this machine; exact diagnostic wording can differ on another GTK build.

This is a conversion step only. It does not edit the SVG, install an icon theme, update an icon cache or replace files in a system directory. Keep the source SVG until the generated image has passed your checks.

1. Confirm the installed command

Check the binary and package version first. Both are ordinary, read-only commands that need no elevated privileges:

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

Read the local option summary too:

$ gtk-encode-symbolic-svg --help
Usage:
  gtk-encode-symbolic-svg [OPTION...] PATH WIDTHxHEIGHT

Help Options:
  -h, --help       Show help options

Application Options:
  -o, --output     Output to this directory instead of cwd

2. Choose the source and size

Set a real source path and decide the rendered dimensions before running the converter. Replace the placeholder with your own file:

input='/path/to/my-symbolic-icon.svg'
size='16x16'
test -r "$input" || {
    printf 'Cannot read %s\n' "$input" >&2
    exit 1
}

• WIDTHxHEIGHT sets the rendered size. It is not a request to preserve the SVG's intrinsic dimensions; use whatever size the consuming application needs.
• Quote paths with spaces. The input must be a symbolic SVG so GTK+ can load and recolour it in the same general way as the source.
• Symbolic only. A decorative, full-colour SVG is not automatically made into a useful symbolic icon by this command.

3. Convert into a separate output directory

Create a new directory for the result, then pass it with --output. This keeps the current directory uncluttered and avoids mixing generated assets with source files:

output='/tmp/my-symbolic-pngs'
mkdir -p "$output"
gtk-encode-symbolic-svg --output "$output" "$input" "$size"

The command normally produces no progress message. A successful exit status means the conversion completed; it does not, by itself, prove the image has the expected visual appearance.

As a concrete, harmless smoke test using the installed utility, this produced a real result from a 16 by 16 symbolic SVG:

$ gtk-encode-symbolic-svg /tmp/gtk-encode-symbolic-svg-1-input.svg 16x16 -o /tmp/gtk-encode-out
$ find /tmp/gtk-encode-out -maxdepth 1 -type f -printf '%f %s bytes\n'
gtk-encode-symbolic-svg-1-input.symbolic.png 104 bytes

The output name is based on the source name and ends in .symbolic.png. Treat that as generated output, not a file to edit by hand.

4. Verify the generated PNG

Inspect the directory and ask file to identify the result:

$ find "$output" -maxdepth 1 -type f -printf '%f\n'
my-symbolic-icon.symbolic.png
$ file "$output/my-symbolic-icon.symbolic.png"
my-symbolic-icon.symbolic.png: PNG image data, 16 x 16, 8-bit/color RGBA, non-interlaced

Your filename and byte count will differ. Check that the output exists, is non-empty, is identified as PNG data, and has the width and height you requested. If your image viewer or GTK application shows an unexpected result, compare the source SVG and the size value before changing other system settings.

5. Use the current directory deliberately

Without -o or --output, the utility writes the PNG in the current working directory. Convenient for a one-off conversion, but an easy distraction when you are standing in a source tree:

$ cd /path/to/icon-work
$ gtk-encode-symbolic-svg my-symbolic-icon.svg 32x32
$ file my-symbolic-icon.symbolic.png
my-symbolic-icon.symbolic.png: PNG image data, 32 x 32, 8-bit/color RGBA, non-interlaced

Before using the default, run pwd and check the directory is where generated files belong. Do not run the command from a shared system icon directory merely because it contains the source: writing there may require elevated privileges and could place an untracked asset among package-managed files.

6. Avoid overwriting a useful result

The utility uses a predictable output suffix. If a file with the same generated name already exists, do not assume rerunning the command gives you an undo path. First choose a new output directory or preserve the old file:

output='/tmp/my-symbolic-pngs-new'
mkdir -p "$output"
gtk-encode-symbolic-svg --output "$output" "$input" 32x32
file "$output/my-symbolic-icon.symbolic.png"

This example only changes the new temporary directory. After checking the replacement, move or copy it into your project's asset directory using that project's normal review process. If you have already generated an unwanted PNG, remove only that derived file after checking its exact path. There is no need for sudo unless the destination itself is protected, and elevated privileges do not fix an invalid SVG or size.

7. Diagnose a failed conversion

If the command cannot open the input, check the path and read permission without changing anything:

ls -l -- "$input"
test -r "$input" && printf '%s\n' 'source is readable'

If it cannot write the result, check the output directory:

ls -ld -- "$output"
test -d "$output" && test -w "$output" && printf '%s\n' 'output directory is writable'

A missing or unwritable directory is an ordinary filesystem problem: fix the path or permissions according to your local policy. Do not make a system directory world-writable, and do not use sudo as a first response.

If a result is produced but has the wrong dimensions, inspect the exact WIDTHxHEIGHT argument and verify the output with file. If the result is not visually suitable as a symbolic icon, return to the SVG source: this command converts a symbolic design, it is not an SVG editor or a general-purpose raster image converter.