Skip to main content

Script-Fu and Python-Fu Basics

Telling GIMP what to do in words instead of clicks

In This Lesson

What Scripting Is For

Everything you do by hand in GIMP — resize, add a layer, apply a filter, export — can also be done by a written instruction. A script is a small program that issues those instructions automatically. Scripting shines for tasks that are repetitive (the same edit on 500 photos), precise (exact numeric values every time), or complex (a multi-step effect you'd rather not click through repeatedly). You don't need to be a programmer to benefit — even a few one-liners save real time.

🎨 An Analogy

Doing a task by hand is following a recipe once. A script is writing the recipe down so a kitchen robot can cook it perfectly, a thousand times, while you do something else.

Script-Fu vs. Python-Fu

GIMP ships with two scripting languages that do the same jobs differently:

Script-FuPython-Fu
LanguageScheme (a Lisp dialect), lots of parenthesesPython, familiar and readable
Built in?Always includedIncluded in most GIMP installs
Best forQuick console commands, existing .scm scriptsLarger, readable automation

They call the same underlying engine (the PDB — Procedural Database), so anything one can do the other can too. Beginners often find Python-Fu easier to read; Script-Fu is unbeatable for a fast one-off in the console.

The Script-Fu Console

The friendliest way to start is the interactive console: Filters → Script-Fu → Console. It's a prompt where you type a command, press Enter, and see the result immediately — no files to install, no restart. It's the perfect sandbox for learning and for quick, one-time jobs.

💡 Experiment Freely — On a Copy

Console commands act on your open image instantly and can't always be undone as one step. Practice on a throwaway copy, and use File → Revert or a fresh duplicate if a command goes sideways.

Your First Command

GIMP procedures follow a naming pattern like gimp-image-flatten or gimp-image-scale. In Script-Fu, a command is wrapped in parentheses with its arguments. A tiny example that flattens the active image: 

(gimp-image-flatten (car (gimp-image-list)))

Here (gimp-image-list) gets the open images and car takes the first one, which is handed to gimp-image-flatten. The same idea in Python-Fu reads more plainly: 

image = gimp.image_list()[0]
pdb.gimp_image_flatten(image)

After a command, call (gimp-displays-flush) in Script-Fu so the canvas updates to show the change.

The Procedure Browser

You'll never memorize every command — you look them up. Filters → Script-Fu → Console has a Browse… button that opens the Procedure Browser, a searchable catalog of every GIMP procedure with its exact name, arguments, and description. Search "scale," find gimp-image-scale, and it tells you precisely what to type.

flowchart LR A[Need a command] --> B[Procedure Browser: search] B --> C[Read name and arguments] C --> D[Type in Script-Fu Console] D --> E[gimp-displays-flush to update]

Browse the procedure, copy its name, run it in the console.

🎓 The PDB Is the Whole API

Every menu command in GIMP is really a PDB procedure. Once you can find and call procedures, you can automate anything the interface can do — the browser is your map to the entire program.

When to Reach for a Script

  • Repetition — the same steps on many files (tomorrow's batch processing).
  • Precision — exact numeric operations every time, no slips.
  • Complex effects — a long recipe you'd rather run than re-click.

⚠️ Don't Over-Automate

Scripting a task you'll do twice costs more than doing it by hand. Automate the genuinely repetitive; for creative, one-off editing, your eyes and hands are still the best tools.

Practice Activities

  1. Open the console. Launch Filters → Script-Fu → Console and run a harmless command like (car (gimp-version)) to see it respond.
  2. Flatten by command. On a copy with several layers, flatten it from the console and flush the display.
  3. Browse a procedure. Use the Procedure Browser to find gimp-image-scale and read its arguments.

Summary

✅ Key Takeaways

  • A script issues GIMP instructions automatically — ideal for repetitive, precise, or complex work.
  • Script-Fu (Scheme) and Python-Fu (Python) both drive the same PDB engine.
  • The Script-Fu Console (Filters → Script-Fu → Console) is the sandbox for learning and one-offs.
  • Commands are PDB procedures like gimp-image-scale; the Procedure Browser lists them all.
  • Automate the genuinely repetitive — don't over-script creative, one-off work.

➡️ What's Next

Next, use scripts others have written: Installing and Using Scripts.

Additional Resources