Debug GIMP Plugin Crashes with Startup Flags

Troubleshooting third-party plugin crashes in GIMP requires capturing real-time console output and crash backtraces that the standard graphical interface hides. By launching GIMP from the command line using specific debugging startup flags, you can force the application to log its entire initialization routine, track procedure database (PDB) registrations, and generate comprehensive stack traces the moment a plugin causes a segmentation fault or unexpected termination.

Essential Startup Flags for Debugging

To capture verbose console output and isolate unstable plugins, use the following command-line flags:

  • --verbose
    Outputs detailed startup information directly to the terminal, including every resource, font, brush, and third-party plugin being queried and loaded into the Procedural Database.
  • --debug-handlers
    Enables GIMP’s internal debugging signal handlers. This ensures the application catches critical operating system signals (such as SIGSEGV or SIGFPE) often caused by unhandled exceptions in compiled C or C++ extensions.
  • --stack-trace-mode always
    Forces GIMP to automatically generate and print a full stack trace to the console whenever a crash occurs. The available arguments are never, query (which prompts the user via a dialog), and always. Setting this to always is critical for automated logging and headless testing.
  • --g-fatal-warnings
    Treats all GLib and GTK warnings as fatal errors. If a third-party plugin misuses the underlying library APIs, GIMP immediately halts and outputs a backtrace at the exact point of the violation rather than attempting to recover and crashing later.

Executing the Debug Command

To view output directly or pipe it into a persistent log file, run the command through your operating system's terminal.

Linux and macOS

Launch your terminal and execute GIMP with the combined debugging options:

gimp --verbose --debug-handlers --stack-trace-mode always > gimp_debug.log 2>&1

For even deeper GLib-level logging alongside GIMP's flags, prepend the G_MESSAGES_DEBUG environment variable:

G_MESSAGES_DEBUG=all gimp --verbose --debug-handlers --stack-trace-mode always

Windows

On Windows, standard gimp-2.10.exe (or your installed version) suppresses console output by default. Use gimp-console-*.exe located inside GIMP's bin directory to ensure output streams to the command line:

"C:\Program Files\GIMP 2\bin\gimp-console-2.10.exe" --verbose --debug-handlers --stack-trace-mode always > debug_log.txt 2>&1

Reading the Log Output

When a third-party plugin fails, check the generated log or console stream near the bottom:

  1. Loading Phase: Look for lines preceded by Querying: to identify which plugin binary or Python script was executing just before the output stopped.
  2. Stack Trace: If the crash occurs after startup, the --stack-trace-mode always flag instructs the debugger (such as GDB or LLDB if installed) to print the call stack, pinpointing the exact shared library (.so, .dll) or system call responsible for the crash.