Using GIMP in Headless Batch Mode with Script-Fu for Reliable Image Pipelines

Problem: Needing a repeatable, GUI‑free way to resize and convert many images

You have a folder of source photos that must be scaled to a fixed width, flattened, and saved as PNG for a web build. Doing this manually in GIMP’s interface is error‑prone and slow, while installing a separate imaging library adds dependencies you’d rather avoid. GIMP already ships with a Scheme‑based scripting engine (Script‑Fu) and can run without a display, making it a candidate for a headless batch job.

Thesis: A small Script‑Fu script invoked via GIMP’s command‑line batch mode can perform the resize‑and‑export task reliably, provided you verify procedure names and handle the quit call explicitly.

Setting up the environment

• GIMP must be installed and reachable from the shell (e.g., gimp-2.10 or gimp).
• No extra Python bindings are required; Script‑Fu is part of the default build.
• Ensure you have read access to the source images and write access to the target directory.

Before writing the script, confirm that the procedures you intend to use exist in your GIMP build. Run a version probe and query the procedural database:

# Run anywhere with a terminal; no special permissions needed.
gimp -i -b '(let* ((version (car (gimp-version)))) (print version) (gimp-quit 0))'

The output shows the version (e.g., "2.10.34"). Next, list the export procedure for PNG:

gimp -i -b '(procedure-list "file-png-save")' 2>/dev/null | head -5

If the procedure name differs (e.g., "file-png-save-defaults" in older builds), adjust the script accordingly.

Worked example: Scale to 1200 px width, export PNG

Save the following Script‑Fu snippet as scale-to-1200.scm:

(define (scale-to-1200 inpath outpath)
  (let* ((image (car (gimp-file-load RUN-NONINTERACTIVE inpath inpath)))
         (drawable (car (gimp-image-get-active-layer image)))
         (width (car (gimp-image-width image)))
         (target-width 1200)
         (scale-factor (/ target-width width)))
    ;; Scale image while preserving aspect ratio
    (gimp-image-scale image target-width (* (car (gimp-image-height image)) scale-factor))
    ;; Flatten to remove layers (optional, depends on workflow)
    (let ((flattened (car (gimp-image-flatten image))))
      ;; Export as PNG
      (file-png-save-defaults RUN-NONINTERACTIVE image flattened outpath outpath))
    ;; Clean up
    (gimp-image-delete image)))

;; Main: process each argument as an input file
(let ((files (cddr (command-line))))
  (while (not (null? files))
    (let* ((infile (car files))
           (outfile (string-append (path-basename infile) "-scaled.png")))
      (scale-to-1200 infile outfile)
      (print (string-append "Processed " infile " → " outfile)))
    (set! files (cdr files)))
  (gimp-quit 0))

Explanation of key parts:

• gimp-file-load RUN-NONINTERACTIVE loads the image without showing the GUI.
• The script computes a scale factor so the width becomes exactly 1200 px; height scales proportionally.
• file-png-save-defaults is the export procedure verified earlier; it writes PNG with default compression.
• Each image is deleted after export to free memory.
• The script ends with (gimp-quit 0); omitting this leaves GIMP running and blocks the shell.

Run the batch job from a shell:

# Assuming the script is in ./scale-to-1200.scm and images are in ./src/
gimp -i -b '(load "scale-to-1200.scm")' -b '(main)' ./src/*.jpg

Where:

• -i starts GIMP without interface.
• -b executes the following Scheme code.
• The first -b loads the script; the second calls the main block defined at the end of the file.
• ./src/*.jpg is passed as command‑line arguments accessible via (command-line) inside the script.
• No special privileges are required; just normal file read/write permissions.

Trade‑offs and limitations

• Startup cost: Each invocation loads the entire GIMP binary and plug‑ins, which is heavier than a dedicated tool like ImageMagick or ffmpeg. For simple resize‑and‑convert pipelines, those tools may be faster.
• Procedure volatility: As noted in the research, procedure names and signatures change between major GIMP releases. A script written for GIMP 2.10 may fail on 2.99 or 3.0 with a "procedure not found" error. Always verify with a version probe and procedural‑database query before relying on a specific call.
• Color‑management differences: Headless runs may use a different default ICC profile than the interactive session, leading to subtle color shifts. If color fidelity is critical, explicitly set the profile via gimp-image-set-color-profile or export with an embedded profile.
• Missing exporters: If a required plug‑in (e.g., for WebP) is not installed, the export call will silently fail and produce no output file. Check the exit status and verify that the expected file appears.

Practical verification steps

1. Run the script on a single test image and inspect the output visually and with a checksum (sha256sum).
2. Check the GIMP process exit code: echo $? after the command; a non‑zero status indicates trouble.
3. Capture stderr: gimp … 2>error.log and look for messages like "procedure undefined" or "Unable to load plug‑in".
4. If the output file is missing or zero‑size, treat the run as failed and adjust the script or install missing plug‑ins.

Once the single‑image test passes, you can safely scale to the full batch, perhaps wrapping the call in a loop or using xargs for parallelism while monitoring resource usage.

Actionable closing

GIMP’s headless batch mode, driven by Script‑Fu, offers a self‑contained way to apply complex image operations without adding extra language runtimes. By confirming procedure names, handling the quit call explicitly, and verifying each step on a small sample, you turn a potentially fragile manual process into a repeatable pipeline. For workloads that stay within GIMP’s feature set—layer manipulations, selective filters, or format conversions that benefit from its internal color handling—this approach can be a pragmatic middle ground between a full GUI script and a lightweight command‑line utility.