gimp-cli-reference

name	gimp-cli-reference
description	Reference for the GIMP command-line interface — non-interactive batch mode, Script-Fu invocation, console binary, and the differences between GIMP 2.10 and GIMP 3.0. Read this before authoring batch ops or Script-Fu calls.

GIMP CLI Reference

Binaries

Binary	Purpose
gimp	Full GUI — avoid for automation
gimp -i	No interface (no GUI windows), but still loads display libs
gimp -i -b <expr>	No interface, run a Script-Fu expression then exit (-b - reads from stdin)
gimp-console (2.10: gimp-console-2.10, 3.0: gimp-console-3.0)	Truly headless — no display libs. Preferred for automation.

Common invocations

# Run a Script-Fu expression
gimp-console -b '(gimp-message "hello")' -b '(gimp-quit 0)'

# Read Script-Fu from stdin
gimp-console -b - <<'SF'
(let* ((image (car (gimp-file-load RUN-NONINTERACTIVE "in.png" "in.png"))))
  (file-png-save RUN-NONINTERACTIVE image (car (gimp-image-get-active-drawable image))
                 "out.png" "out" 0 9 1 1 1 1 1)
  (gimp-image-delete image))
(gimp-quit 0)
SF

# Flatpak equivalent
flatpak run --command=gimp-console org.gimp.GIMP -b '...' -b '(gimp-quit 0)'

GIMP 2 vs GIMP 3

• GIMP 3 uses Script-Fu (TinyScheme) still, but the Python-Fu console was replaced by GObject Introspection bindings (Python 3 + gi).
• Default user config dir: ~/.config/GIMP/2.10/ vs ~/.config/GIMP/3.0/.
• Procedure names: most gimp-* PDB calls are stable; some renames in 3.0 (e.g. gimp-image-get-active-drawable → gimp-image-get-selected-drawables returning a vector).

Always end Script-Fu batch sessions with (gimp-quit 0) or the process hangs.