How to Convert Images Using GIMP Headless Mode

This article explains how to execute the GNU Image Manipulation Program (GIMP) in headless mode via the command line to automate image format conversion. It covers the required command-line switches, the exact Script-Fu syntax needed to open, convert, and save images non-interactively, and a practical example for converting common file formats like PNG to JPEG.

The Headless Conversion Command

To process and convert an image entirely without a graphical user interface, call the gimp binary with the -i (or --no-interface) flag and execute Scheme (Script-Fu) commands using the -b (or --batch) flag.

Here is the complete syntax to convert an image named input.png to output.jpg:

gimp -i -b '(let* ((image (car (gimp-file-load RUN-NONINTERACTIVE "input.png" "input.png")))
                  (drawable (car (gimp-image-get-active-layer image))))
              (gimp-file-save RUN-NONINTERACTIVE image drawable "output.jpg" "output.jpg")
              (gimp-image-delete image))' \
     -b '(gimp-quit 0)'

Command Breakdown

  • -i: Disables the graphical user interface completely, running GIMP headlessly.
  • -b '<command>': Evaluates a batch command written in Script-Fu (Scheme syntax).
  • let*: Binds local variables within the batch process:
    • image: Loads the source file into memory using (gimp-file-load RUN-NONINTERACTIVE filename raw-filename).
    • drawable: Retrieves the active layer of the image using (gimp-image-get-active-layer image), which is required by the export procedure.
  • gimp-file-save: Saves the loaded image to the destination filename using the specified active drawable. GIMP automatically determines the export format based on the file extension (.jpg, .png, .webp, etc.).
  • gimp-image-delete: Flushes the image from memory to prevent memory leaks during execution.
  • -b '(gimp-quit 0)': A secondary batch argument that instructs the GIMP process to terminate immediately with an exit code of 0. Omitting this command will cause the process to hang in the terminal after completing the file export.

Automating Multiple Files

To convert multiple files in a directory using a standard Bash loop, wrap the command in a shell script:

for file in *.png; do
  output="${file%.png}.jpg"
  gimp -i -b "(let* ((image (car (gimp-file-load RUN-NONINTERACTIVE \"$file\" \"$file\")))
                    (drawable (car (gimp-image-get-active-layer image))))
                (gimp-file-save RUN-NONINTERACTIVE image drawable \"$output\" \"$output\")
                (gimp-image-delete image))" \
       -b '(gimp-quit 0)'
done