Changes in ScriptFu v3

This tells how to edit v2 scripts so they will run in GIMP 3. It also lists enhancements to ScriptFu and its language.

ScriptFu version 3 is the ScriptFu that is part of GIMP version 3. ScriptFu is not separately versioned.

Why these changes now?

GIMP 3 is a major version change with new features. A major version allows breaking API, meaning old plugins and scripts might not work.

The GIMP developers understand these changes may be onerous but a major version is necessary to move forward.

A lucky few existing scripts may work in GIMP v3 without change. Most scripts, however, will require edits because:

many PDB procedures are obsolete or renamed, or their signature changed
the symbol SF-VALUE is obolete
the symbol SF-BRUSH is changed

Once you edit a script for these changes, the script won’t work in GIMP v2.

The other changes are enhancements to ScriptFu and might not affect an existing plugin. You need only understand those enhancements when you want to use them.

Changed PDB API

You must edit your scripts to conform to version 3 of the PDB API. For detailed information and to not repeat ourselves, see: Adapting scripts to PDB version 3

`SF-VALUE` type of argument is obsolete

You must edit v2 scripts and replace the symbol SF-VALUE.

Formerly, a SF-VALUE argument let a user enter garbage for an argument, which caused an error in the script. SF-ADJUSTMENT or SF-STRING is more user-friendly.

Use `SF-ADJUSTMENT` for most use cases

In v2, SF-VALUE declared a formal argument that is an unquoted, arbitrary string. Usually, SF-VALUE was used for an integer valued argument. In the dialog for a script, ScriptFu showed a text entry widget. Usually the widget showed a default integer literal, but the widget let you enter any text into the string.

You usually will replace it with an SF-ADJUSTMENT kind of formal argument, where the “digits” field of the SF-ADJUSTMENT is 0, meaning no decimal places, i.e. integer valued. You must also provide other fields, e.g. the lower and upper limits. Example:

Scheme

SF-VALUE      "Font size"  "50"
=>
SF-ADJUSTMENT "Font size" '(50 1 1000 1 10 0 SF-SPINNER)

Here, in the seven-tuple, the 0 denotes: no decimal places.

Another example, where you formerly used SF-VALUE to declare a formal argument that is float valued:

Scheme

SF-VALUE      "Lighting (degrees)"  "45.0"
=>
SF-ADJUSTMENT "Lighting (degrees)" '(45.0 0 360 5 10 1 SF-SLIDER)

Here, the 1 denotes: show 1 decimal place, for example “45.0”, in the dialog widget.

Also, in v2, a SF-VALUE argument let a user enter a float with arbitrary precision, e.g. “0.00000001”

That is no longer possible. You as a script author must use SF-ADJUSTMENT and specify the maximum precision that makes sense. The user won’t be able to enter a value with more precision (more digits after the decimal point.) You should understand the math of your algorithm and know what precision is excess in terms of visible results. Example:

Scheme

SF-ADJUSTMENT "Lighting (degrees)" '(45.0 0 360 5 10 4 SF-SLIDER)

Here, the user will only be able to enter four decimal places, for example by typing “0.0001” into the widget.

Use `SF-STRING` for some use cases

If you actually need arbitrary precision, use SF_STRING to get a string, and then your plugin can eval the string to get a Scheme numeric of the maximum precision that Scheme supports.

Similarly, in v2, a SF-VALUE argument let a user enter executable Scheme code, say “’(1 g 1)”, which is a list literal, to be injected into a Scheme call to a plugin. That use is no longer possible. If you must do that, use SF_STRING to get a string, and then your plugin can eval the string.

`SF-BRUSH` type of argument is changed

You must edit v2 scripts to only use the brush name from the symbol SF-BRUSH.

In version 2, an SF-BRUSH triplet had a list for the third element of the triple.

In version 3, Script-Fu only reads the first element of the list, the name of the brush. Scripts that used a brush may need porting.

You can optionally install scripts like plugins in other languages

We recommend this for new plugins.

In v2 all ScriptFu scripts were installed in a /scripts directory.

In v3 you can install Script-Fu scripts to a /plug-ins directory, like plugins in other languages. This helps isolate plugins. See: Old and new styles of Script-Fu plugins

Registration function script-fu-register is now deprecated

You should not use script-fu-register in new ScriptFu scripts.

ScriptFu v2 has only script-fu-register. It is a generic function used to declare procedures that are either: generic procedures (operating without an image) or filters/renderers (operating on an image)

While deprecated, script-fu-register should still work. But the plugin will:

have an old look-and-feel, not automated dialog, and will be missing handling of persistent settings
you can only declare a plugin taking one drawable (i.e. layer or mask)

In the future, the GIMP project might obsolete script-fu-register.

New registration functions let a plugin dialog have a new look-and-feel and improved settings. These are:

Using the v3 dialect for PDB return values

We recommend this for new scripts.

ScriptFu in GIMP version 3 optionally interpret a new, improved dialect. For detailed information and to not repeat ourselves, see Using the version 3 dialect for PDB values

`FALSE` and `TRUE` symbols are deprecated

We recommend not using TRUE and FALSE in new scripts, except for an SF-TOGGLE argument.

TRUE and FALSE duplicated concepts already in the Scheme language. The ScriptFu language can be simpler and smaller.

Instead of using them, you should use the v3 dialect and use the Scheme language symbols #f and #t.

That is because, in Scheme, all values are truthy except for #f. FALSE (0) is truthy so not equivalent to #f. Example logically examining a variable for truth:

Scheme

(if (= shadow TRUE) ...
=>
(if shadow ...

In the v3 dialect, a PDB procedure returning a single Boolean (a predicate) returns one element, for example #f or #t. Example calling a PDB procedure taking a boolean:

Scheme

(gimp-context-set-feather TRUE)
=>
(gimp-context-set-feather #t)

You still need to declare or compare boolean SF_TOGGLE arguments to a script with TRUE and FALSE. They are not #t and #f.

Example declaring a script’s SF_TOGGLE arguments can still use TRUE and FALSE.

Scheme

SF-TOGGLE     "Gradient reverse"   FALSE

Comparing a boolean argument to a script must remain as in v2 dialect:

Scheme

(if (= should-invert TRUE)
    ; do invert )

Using the `quit` function to abort a script

We recommend using quit to declare errors along with gimp-message.

Formerly, scripts usually called gimp-message on errors, without yielding an error to the caller. This is because a call such as (quit -1) did abort the script, but did not return an error to the caller (usually the GIMP app) and did not return the error code.

In ScriptFu v3 quit causes the interpreter to stop interpreting a script and yield an error of type GimpPDBStatus. That is, it immediately returns an error to the GIMP app or other caller. The GIMP app will show an error message including the phrase “script quit with error code x.”

Even so, you should still call gimp-message just before calling quit, with an informative error message. The numeric code that quit prints is not informative to users, only to the script author. See: The quit function

Using the `display` function to write to the terminal

We recommend using the display function to help debug a script or to log, but not to prompt for user input.

Display is a Scheme function, in the R5RS standard. It should write a string to any open terminal (e.g stdout). But, in ScriptFu v2, it did not write to a terminal. Display wrote to a stream which was returned to the GIMP app, and usually discarded (unless an error occurred, and then the stream was the prefix of the error message.)

In ScriptFu v3, it does. You will see the output in any terminal in which the GIMP app was started (which is optional, and not usually done on a graphical desktop.). See: The display function

Last updated on November 16, 2025

Internationalizing GIMP Scheme Plugins Adapting scripts to PDB version 3