Run Script-Fu Scheme in the GIMP Console

This guide explains how to write and execute Scheme-based Script-Fu commands directly in GIMP's interactive Script-Fu Console. You will learn the fundamental syntax of Scheme, how to structure multi-step commands using local variable bindings, and how to query and execute GIMP's Procedural Database (PDB) functions directly from the command line interface without writing external plugin files.

Accessing the Script-Fu Console

To open the console in GIMP, navigate to the top menu and select Filters > Development > Script-Fu > Console (or Filters > Script-Fu > Console in older GIMP releases). The console provides an interactive Read-Eval-Print Loop (REPL) where you can type commands into the bottom input field and view the results in the main output window.

Basic Scheme Syntax

Script-Fu is based on TinyScheme, a lightweight implementation of the Scheme programming language. It uses prefix notation, meaning the operator or function name always comes first, enclosed within parentheses along with its arguments:

(function-name argument1 argument2 ...)

Basic mathematical and string operations follow this structure:

(+ 10 25)
(* 4 5 2)
(string-append "Hello, " "GIMP!")

Calling GIMP PDB Functions

GIMP exposes its functionality through the Procedural Database (PDB). In Script-Fu, PDB functions are invoked like standard Scheme procedures, typically using hyphenated naming conventions.

Most GIMP functions return values wrapped inside a list. When capturing a return value (such as an image or layer ID), you must use the car function to extract the first element:

(car (gimp-image-new 800 600 RGB))

To search for available functions, argument types, and return signatures, click the Browse... button at the bottom of the Script-Fu Console window to inspect the PDB.

Writing a Multi-Command Macro

To run a series of sequential commands or define temporary variables in the console, wrap the logic in a let* block. The let* form allows each defined variable to reference variables declared before it in the same block.

The general structure is:

(let* (
       (variable1 value1)
       (variable2 value2)
      )
  (statement1)
  (statement2)
)

Complete Console Example

Paste the following macro into the console input line to create a new 500x500 image, add a transparent layer, fill it with a color, and display it in the workspace:

(let* (
       (width 500)
       (height 500)
       (image (car (gimp-image-new width height RGB)))
       (layer (car (gimp-layer-new image width height RGBA-IMAGE "Background" 100 LAYER-MODE-NORMAL-LEGACY)))
      )
  (gimp-image-insert-layer image layer 0 0)
  (gimp-context-set-foreground '(0 128 255))
  (gimp-drawable-fill layer FILL-FOREGROUND)
  (gimp-display-new image)
)

Executing the Code

  1. Paste or type the entire expression into the single-line input field at the bottom of the console.
  2. Ensure all opening parentheses have corresponding closing parentheses; mismatched brackets will cause a syntax error or leave the interpreter waiting for input.
  3. Press Enter to execute. The output window will return the value of the last evaluated expression or display an error message if an invalid identifier or argument type was provided.