ArtsAutosBooksBusinessEducationEntertainmentFamilyFashionFoodGamesGenderHealthHolidaysHomeHubPagesPersonal FinancePetsPoliticsReligionSportsTechnologyTravel
  • »
  • Technology»
  • Consumer Electronics & Personal Gadgets»
  • Portable Electronics

Gimp: How To Write a Script-Fu Macro

Updated on December 11, 2014

How to Write GIMP Macros to Speed up Your Photoediting

Gimp is a very powerful photoediting tool similar to Adobe Photoshop (except it is free) and like with Photoshop, macros or scripts can be written to increase productivity and to speed up repetitive tasks, like reducing the size of a lot of photos so you can email them, or adjusting the levels, contrast or saturation, but unlike some other programs the task of creating macros cannot be replaced or simplified with a macro-recording facility (i.e. perform the task once and record your actions, then repeat it just by "replaying" the macro)

GIMP does however have a "Script-Fu Procedure Browser" which aids the development of a Script-Fu macro. Script-Fu is a version of Scheme which is itself a version of Lisp.

This articles deals with how to create and use macros for this useful tool and how to use the Apple Mac command-line to run Gimp in batch mode (i.e. repeat a series of photoediting tasks on many photo files).

Script-Fu Procedure Browser

The Script-Fu Procedure Browser is a fairly intuitive browser that helps to find the function you want, perhaps corresponding to a GIMP menu function without having to resort to reading a manual. It also gives syntax and arguments for each function and a useful search feature.

To open the Script-Fu Procedure Browser, from the GIMP window use the following menu:

"GNU Manipulation Program": Filters -> Script-Fu -> Consule

(This may vary depending on the version of GIMP being used)

Once you know the syntax of the various commands you need you can put them together to form a function that performs the series of operations you require.

GIMP from the Linux/Unix command-line: Mac OSX

Darwin Terminal Command-Line

Gimp commands can be used directly from the command-line.

Start a Terminal window either from X11 (X11 is Apples version of the X Server and must be installed in order to run GIMP see this article about installing GIMP if you don't have X11) and start gimp using the full path to the gimp executable file, which for an Apple Mac would probably be:

X11 Applications -> Terminal


Macintosh HD -> Applications -> Utilities -> Terminal

(from Linux just open an xterm)

Start gimp in batch-mode either with the full path as below (or just gimp -b if you are using linux)

/Applications/ -b -

Then type the Script-Fu commands at the gimp prompt e.g.

> (gimp-image-new 256 256 RGB)


>(gimp-display-new 1)


The (1) is the image-id for the new-image, returned by the first function and may not be (1) and is the argument in the second command.

Defining a function

Now you have established the commands you want to use they can be combined into a new function inside a let* statement. e.g. here is an example of creating a new image, passing the image-id to the variable img-id, creating a new layer (lay-id) filling that layer, then displaying the image created:

(define (create-simple-image)

(let* ((img-id (car (gimp-image-new 512 512 RGB)))

(lay-id (car (gimp-layer-new img-id 512 512 RGB-IMAGE "layer-name" 100 NORMAL-MODE))))

(gimp-drawable-fill lay-id BG-IMAGE-FILL)

(gimp-image-add-layer img-id lay-id 0)

(gimp-display-new img-id)


the image-id ("img-id") is then returned after the function is run as shown below:

> (create-simple-image)


car is the first part of a list, cdr the rest of the list and cadr is the first part of the rest of the list (the same as in the languages Lisp and Skill)

O.K. That's all very well, but not very useful for manipulating photographs. If you have scanned photos from a digital scanner or photos in a digital camera you may want to process them for use on a web-page or emails etc.

Here is an example of function that will read a jpeg file, adjust the levels (gimp-level-stretch automatically adjusts the levels histogram) and change the size of the photo (i.e. change the number of pixels) then writes out a new jpeg file:

(define (photo-shrink width height input output)

(let* ((image (car (file-jpeg-load 1 input output)))

(drawable (car (gimp-image-active-drawable image))))

(gimp-levels-stretch drawable)

(gimp-image-scale image width height)

(file-jpeg-save 1 image drawable output output 0.8 0 1 1 "" 0 1 0 0))


alternatively the function (file-jpeg-load ... ) could have been used in the same way to read a TIFF file from a scanner (and other functions exist for other file formats)

This can then be called from the Gimp command-line like this:

> (photo-shrink 100 100 "IMG_0665.JPG" "IMG_0665-z.JPG")

which will read the file "IMG_0665.JPG", fix the exposure and shrink it to 100 x 100 pixels and output the file "IMG_0665-z.JPG"

Scheme Programming Language - GIMP Script-Fu

Simple "Batch" Process

So now we have a function to manipulate a photo file, but how do we use it to manipulate lots of files all at once?

The quickest way (if not the most elegant way) to do this is just to paste the function into Gimp for each file in a directory. i.e. list the files in the directory, dump the file-names to a file and build a script, then paste it into the Gimp command-line.

e.g. from a Terminal window in the appropriate directory

> ls > simple-script

then edit the file simple-script to define the function photo-script function then call the photo-shrink function for each jpeg file then start gimp and paste the file:

/Applications/ -b -

Welcome to TinyScheme, Version 1.38

Copyright (c) Dimitrios Souflis

> (define (photo-shrink width height input output)

(let* ((image (car (file-jpeg-load 1 input output)))

(drawable (car (gimp-image-active-drawable image))))

(plug-in-autocrop 1 image drawable)

(gimp-levels-stretch drawable)

(gimp-image-scale image width height)

(file-jpeg-save 1 image drawable output output 0.8 0 1 1 "" 0 1 0 0))


(photo-shrink 100 100 "IMG_0665.JPG" "IMG_0665-z.JPG")

(photo-shrink 100 100 "IMG_0668.JPG" "IMG_0668-z.JPG")

(photo-shrink 100 100 "IMG_0667.JPG" "IMG_0667-z.JPG")

(photo-shrink 100 100 "IMG_0666.JPG" "IMG_0666-z.JPG")

(photo-shrink 100 100 "IMG_0671.JPG" "IMG_0671-z.JPG")

(photo-shrink 100 100 "IMG_0670.JPG" "IMG_0670-z.JPG")

(photo-shrink 100 100 "IMG_0669.JPG" "IMG_0669-z.JPG")

(photo-shrink 100 100 "IMG_0672.JPG" "IMG_0672-z.JPG")

This will have fixed the exposure (i.e. run auto-levels) for every file listed, auto-cropped any unused pixels round the picture, resized to 100 x 100 pixels and output a jpeg. This could easily be altered to read a TIFF file (or any other format) from a digital scanner, auto-crop the blank edges (function plug-in-autocrop or plug-in-zealouscrop) fix the levels, resize and convert to JPEG format.

This method works in an Apple Mac Terminal window, but if you are editing a lot of large files could result in memory issues, so another way to run Gimp from the Apple Terminal command line is to feed the function definition and opperations into gimp from a file:

> /Applications/ -b - < file.txt

where file.txt contains the function definition above and one or more function-calls, followed by the function (gimp-quit 0) to return control to unix. This can then be repeated for each file name in the directory although a new file.txt for each filename, or some copying/moving of files between each gimp run (see the next section)

This is a bit of a hack, but if you want to do this properly you will need to use the script-fu-register function to register the function and script-fu-menu-register if you want to add it as a menu item and save the scripts in the default scripts directory so that gimp can pick them up from a proper batch run (see below)

Registering a Function

After writing a function it can then be registered to allow it's use from a GIMP menu, using the script-fu-register function. Alternatively after defining the function on the GIMP command line it can be used repeatedly from the command line or as a batch process (See below)


"macro-name" ; Function Name

"macro-name" ; Menu Label

"Do something to a photo..."

"Andy" ; author

"Andy" ; copyright

"2009-11-19" ; date created

"" ; image type that script works on

; Any Other Variables that need to be defined... (need to check documentation for the these options)


The scripts should be saved to a text file in directory ~/.gimp-2.6/scripts/ e.g. create-simple-image.scm then run

Script-Fu -> Refresh Scripts

to load the scripts in the scripts directory.

Running Gimp in Batch Mode

From the command Line

to invoke Gimp from unix or linux either use command line or a shell script similar to the following:

gimp --display :1.0 -c -i -d -b '(macro-name arg1 arg2 100 "file1" "file2")' '(gimp-quit 0)'

where macro-name is the name of an already defined and registered function that takes two file-names as input (file1 and file2) and two other arguments (arg1 and arg2); reads file1 performs some action on that file and saves to a new file.

Simple shell script for batch Gimp to run a macro on every file in a directory:


for file in *; do

echo Reading: $file;

/Applications/ --display :1.0 -c -i -d -b '(macro-name Arg1 Arg2 "'$file'" "'$file'2")' '(gimp-quit 0)'


This didn't work from the Apple Mac; for a start for Apple Mac terminal Window ("Darwin" version of unix) the full path to gimp and an extra hyphen at the end will be required instead of just gimp: e.g. /Applications/ -c -i -d -b -

but I found the following did work for the Apple Mac (and the function doesn't need to be registered because it is defined each time it is called):

create a text file gimp-batch-script2:

(define (gimp-photo-fix input)

(let* ( (output (string-append input ".jpg")) (image (car (file-tiff-load 1 input out


(output (string-append input ".jpg"))

(drawable (car (gimp-image-active-drawable image))))

(plug-in-autocrop 1 image drawable)

(gimp-levels-stretch drawable)

(file-jpeg-save 1 image drawable output output 0.8 0 1 1 "" 0 1 0 0)))

(gimp-photo-fix "temp")

(gimp-quit 0)

and bin file gimp-batch-script:


for file in *; do

echo Working on file: $file;

cp $file temp;

/Applications/ -b - < ./gimp-batch-script2;

mv temp.jpg $file.jpg


> chmod 775 ./gimp-batch-script

then run it:

> ./gimp-batch-script

That will copy each TIFF file in turn to temp, start gimp and run the script reading temp and writing temp.jpg then copy temp.jpg to the original filename (with a .jpg appended). O.K. not elegant, but it works

Please Leave Some Feedback

    0 of 8192 characters used
    Post Comment

    • robertred24 profile image

      robertred24 4 years ago

      If you don't want to spend a lot of money for Photoshop, then GIMP is for you.

    • profile image

      mediawizard lm 4 years ago

      Great lens AndyPro, I've bookmarked it for reference!

      Will try it out

    • profile image

      Bartukas 4 years ago

      interesting lens thanks

    • RightOrWrong LM profile image

      RightOrWrong LM 5 years ago

      Thanks for all of thank. I can do with all the Gimp help I can get.

    • RightOrWrong LM profile image

      RightOrWrong LM 5 years ago

      Thanks for all of thank. I can do with all the Gimp help I can get.

    • Andy-Po profile image

      Andy 5 years ago from London, England

      @myriam-luce-3: Sorry. I think I misunderstood your original question. The "local file" I was referring to was local to the wrapper script that I had written that called GIMP for each file in the directory in which I was running the script. I was running GIMP from Unix/Linux, so the file was passed to GIMP by the wrapper script and I didn't need to worry about how GIMP itself handled the file names/paths etc.

      It sounds like you have solved the problem anyway. Thanks very much for the comments.

    • profile image

      myriam-luce-3 5 years ago

      @Andy-Po: "Sleep on it" is very good advice. This morning, I woke up with a start my mind screaming (CAR())!! and I fixed my script, so "C:/Test/test.png" works, now.

      However, for future use, I'd still like to know what a local file name is. If I'm running a script from GIMP's GUI Filters menu, the script has to be saved in the /scripts folder of GIMP. This is where I would have to save my images if I wanted to use "test.png" rather than the full path? I know the answer is in "e.g. from a Terminal window in the appropriate directory", but I'm very sorry, I don't understand what you mean :(

      Thanks so much for answering, and quickly, too!!

    • profile image

      myriam-luce-3 5 years ago

      Good article, but there's one thing I don't get about these scripts. Your "img_1234134.jpg" filename - where does GIMP fish it? How does it know where it is on your C:?? Is it in some particular relative folder of GIMP? If you want to give an absolute path, how would you proceed? "C:/users/Desktop/Folder"? or am I forgetting a / somewhere?

    • profile image

      Didge 5 years ago

      Superb lens!

    • profile image

      anonymous 5 years ago

      Returning with a little angel dust for this Gimp help excellence!

    • Andy-Po profile image

      Andy 5 years ago from London, England

      @SteveDOF: Good point. I can create a macro in no time and I enjoy it, but a macro recorder is the easiest way to do it if you don't like script-writing.

    • BobZau profile image

      Bob Zau 5 years ago

      I've used GIMP, but have yet to utilize script, Thanks for the tutorial.

    • profile image

      SteveDOF 5 years ago

      Gimp is an impressive endeavour, it looks extremely useful and highly polished, but as an illustrator, the one thing that stops me dead, even before downloading it, is the lack of a built-in macro recorder.

      I don't care how easy and "fun" script writing is. It isn't something I am even vaguely interested in. If you enjoy it fine, I wish you well, but I draw and paint, that's my job, it's my past-time, that is what I want to use a paint program for, not to write scripts.

      I'm sure there are others like me, how many is impossible to say, but the time and yes, money, that a good in-built macro recorder saves is enormous. As far as I can see from watching many videos and reading about Gimp, Photoshop's actions recorder remain it's single biggest tool advantage over Gimp.

      Give me a built-in macro recorder that rivals Pshops actions and I'd download gimp tomorrow, but until then, it would be pointless, from my point of view, to even try the program out.

    • mojweb profile image

      mojweb 6 years ago

      Great tutorial. Thanks.

    • profile image

      BaseCandy 6 years ago

      thanks a lot

    • fiftysquid profile image

      fiftysquid 6 years ago

      Thanks Andy, I'm going to bookmark this lens for future reference! Very informative, thanks!

    • chgreen profile image

      chgreen 6 years ago

      wow, what a lot of hard work. Thanks.

    • tstandiford profile image

      tstandiford 6 years ago

      Awesome! I've looked everywhere for something like this.

      Thanks so much for sharing this.

    • Andy-Po profile image

      Andy 6 years ago from London, England

      @gypsyman27 lm: I forgot to say, we also had a similar joke: "LISP stands for Lots of Irritating Superfluous Parentheses"

    • sukkran trichy profile image

      sukkran trichy 6 years ago from Trichy/Tamil Nadu

      thank you very much for the useful info about photo editing with gimp.

    • Andy-Po profile image

      Andy 6 years ago from London, England

      @gypsyman27 lm: Thanks very much. I'm glad this was useful. LISP was used as the basis for quite a few CAD packages, I think. I used it in the form of "Skill" for many years, which was used in some silicon chip design industry CAD packages, so I was quite pleased to find out that is was the basis of Gimp too.

      Look forward to seeing you next time I'm in Virginia ;-)

    • gypsyman27 lm profile image

      gypsyman27 lm 6 years ago

      Andy, this lens is a saving grace for me. I've been running Gimp on my laptops and my son's desktop, but they are PCs no Macs. Now I have this Mac, because they're supposed to be better for artists, but I'm having a lot of trouble installing the Mac version of Gimp. Now I see where I wandered off the path and I realize what I need to do, so I'm bookmarking this page for help in the future. Thank very large for sharing this information. If you're in the states stop by my place in Virginia and I'll try and make us even.:~) I note that Gimp is written in a language similar to LISP. We used to use a form of LISP in one of our CAD packages. It was AutoCAD, and AutoLISP, to make a long story short (too late) we used to call it Lost In Stupid Parenthesis. I know it's corny, thanks again. See you around the galaxy...

    • ElizabethJeanAl profile image

      ElizabethJeanAl 6 years ago

      Great info!

    • ElizabethJeanAl profile image

      ElizabethJeanAl 6 years ago

      Great info!

    • profile image

      Valerie Anne Kell 6 years ago

      Great Photography sweetheART &amp; good news about gimp ;~} Valz

    • Philippians468 profile image

      Philippians468 6 years ago

      im really impressed with your knowledge! cheers

    • profile image

      anonymous 6 years ago

      YOu sure know what you're doing, my friend!

    • Michey LM profile image

      Michey LM 7 years ago

      Excellent learning to mastermind Gimp, I came back to bless this lens. Always from your lens I learn something, and this one is no exception.


    • cbessa profile image

      cbessa 7 years ago

      Thanks for the tips. I am starting to use GIMP as a PS substitute and will be pretty useful, because i am still kind of shaky with Gimp interface and ways.

    • MargoPArrowsmith profile image

      MargoPArrowsmith 7 years ago

      Great reference, thanks for the work and information

    • Michey LM profile image

      Michey LM 7 years ago

      I download Gimp, but I didn't get over the learning curve. I am still using Corel Photo-Paint... just because I use to it. I am not lazy, and I like to learn new thinks, but my time is very limited, so I have t relay in short cuts and do my nest.

      Great lens Andy.

    • OhMe profile image

      Nancy Tate Hellams 7 years ago from Pendleton, SC

      I've been wanting to try Gimp but haven't yet. Most of this is way over my head but I did appreciate learning a little more about Gimp. One of these days I will get up the nerve to try it. I like my old Picture It program and so far it is working fine for me. Blessed.

    • profile image

      anonymous 7 years ago

      Thank you for the is good.

    • profile image

      julieannbrady 7 years ago

      @julieannbrady: Ah ... this still fascinates me! Go ahead, say Script-Fu Macro fast three times!

    • AuthorNormaBudden profile image

      AuthorNormaBudden 7 years ago

      Well, I'm in the process of updating my Purple Star lenses so will definitely drop back here again (since it's growing late) tonight. Congratulations on pulling another Purple Star in and thanks for letting me know earlier. I've just gotten around to featuring it apologies for the delay.

    • hlkljgk profile image

      hlkljgk 7 years ago from Western Mass

      gimp is a great tool; thanks for the info - congrats on your purple star :)

    • ElizabethJeanAl profile image

      ElizabethJeanAl 7 years ago

      I bought a new camera this spring. I've been using Photoshop to edit them but I need to check this out. Photoshop and I are not on the best of terms.

      Thanks for sharing


    • Andy-Po profile image

      Andy 7 years ago from London, England

      @julieannbrady: That's an interesting thought. It wouldn't be possible to use this macro language to auto generate or update lenses though. It only works on image files. I suspect Squidoo wouldn't want the lenses auto generated anyway as some people might use it to generate lots of "Spam" lenses. An auto update would be useful though.

    • profile image

      julieannbrady 7 years ago

      Wow! This is hugely interesting ... and then I started thinking outside the box, as to what macros would help lensmasters in their publishing / updating of a portfolio of lenses. Do you supposed somebody already has written that macro for automating that process? I thought I heard or read something about just that. Very interesting Andy!

    • profile image

      anonymous 7 years ago

      This lens is awesome. I love it. I am going to tell my editors on my Thai News website to write something about this lens and probably feature it.

      I will comment here again once we do.

      Great Work

    • Mihaela Vrban profile image

      Mihaela Vrban 8 years ago from Croatia

      Great tutorial! :) Well done!

    • Sylvestermouse profile image

      Cynthia Sylvestermouse 8 years ago from United States

      I have asked for Photoshop for Christmas, so I will be back for the additional help! Thanks!

    • ZenandChic profile image

      Patricia 8 years ago

      Over my head... I just use photobucket so I don't have to figure it out too much.

    • Laniann profile image

      Laniann 8 years ago

      Beautiful photographs, as always. I can see how this would save a lot of time. Good clear instructions.

    • aka-rms profile image

      Robin S 8 years ago from USA

      Great tutorial!