How to Freeze and Thaw GIMP Undo Stack

Automating repetitive graphic operations with GIMP scripts can significantly degrade processing speeds if the application records every intermediate step into the undo history. This guide details the specific GIMP Procedural Database (PDB) calls used to freeze and thaw the undo stack, explaining how temporarily disabling undo event logging maximizes script execution performance without discarding existing project history.

The API Calls: Freeze and Thaw

To prevent GIMP from recording operations to the undo buffer during an intensive script, use the following procedural calls:

  • To freeze the undo stack: gimp-image-undo-freeze (Script-Fu) or pdb.gimp_image_undo_freeze(image) (Python-Fu)
  • To thaw the undo stack: gimp-image-undo-thaw (Script-Fu) or pdb.gimp_image_undo_thaw(image) (Python-Fu)

Both functions require a single parameter: the target image object.

How Undo Freezing Works

Every drawing, filtering, or transformation step executed by a script normally pushes state data to GIMP's undo stack, consuming CPU cycles and RAM.

Calling gimp-image-undo-freeze suspends the recording of undo events. Unlike gimp-image-undo-disable—which purges all existing undo history permanently—freezing keeps the prior undo history intact while simply ignoring any new actions performed while frozen.

When your script finishes its batch operations, invoking gimp-image-undo-thaw reactivates undo tracking.

Implementation Example in Python-Fu

# Suspend undo tracking to increase performance
pdb.gimp_image_undo_freeze(image)

try:
    # Perform intensive batch tasks here
    # (e.g., thousands of pixel edits, multiple layer operations)
    pass
finally:
    # Ensure undo tracking is always re-enabled
    pdb.gimp_image_undo_thaw(image)

Implementation Example in Script-Fu

;; Freeze undo recording
(gimp-image-undo-freeze image)

;; Execute batch operations here

;; Thaw undo recording
(gimp-image-undo-thaw image)

Critical Usage Considerations

  • Balanced Pairing: Freezing and thawing operate via an internal counter. Every call to freeze must be matched by a corresponding call to thaw. If freeze is invoked twice, thaw must also be called twice before undo logging resumes.
  • User Experience: Any actions taken while the stack is frozen cannot be undone by the user. If your script should appear to the user as a single undoable action rather than being completely omitted from history, use gimp-image-undo-group-start and gimp-image-undo-group-end instead. However, for sheer execution speed in non-interactive batch processing, freeze and thaw deliver the lowest overhead.