| name | gimp-headless |
| description | Run GIMP headlessly as a command line application using batch mode. Use this skill when asked to run GIMP scripts, manipulate image layers automatically, or process images with GIMP tools without opening the GUI. |
GIMP Headless Batch Mode Skill
GIMP (GNU Image Manipulation Program) can be executed in a powerful "headless" batch mode. This allows AI agents to manipulate images via command-line execution without spawning graphical windows.
Core Command & Flags
If running on Linux, standard execution involves the following core flags:
gimp -i -b '<batch-command>' -b '(gimp-quit 0)'
-i or --no-interface: Run without the GUI. This is the most critical flag for headless execution.-b or --batch: The batch command to execute. You can string multiple -b commands together.-d or --no-data: Do not load brushes, gradients, palettes, or patterns (speeds up execution if you don't need them).-f or --no-fonts: Do not load fonts (speeds up execution).--batch-interpreter <interpreter>: Allows switching from script-fu-eval (default Scheme) to python-fu-eval (Python).
Approach 1: Script-Fu (Scheme)
The default batch interpreter uses Script-Fu. This requires passing LISP-like commands.
Example: Batch Resizing an Image
gimp -i -b '(let* ((image (car (gimp-file-load RUN-NONINTERACTIVE "input.png" "input.png"))) (drawable (car (gimp-image-get-active-layer image)))) (gimp-image-scale image 800 600) (gimp-file-save RUN-NONINTERACTIVE image drawable "output.png" "output.png") (gimp-image-delete image))' -b '(gimp-quit 0)'
Approach 2: Python-Fu (Python)
You can also execute Python directly natively through GIMP's API. This is heavily preferred for complex scripts.
Example: Calling a Python script
Provide a .py script (e.g., process.py), and then execute it via:
gimp -i --batch-interpreter python-fu-eval -b "import sys; sys.path.append('.'); import process; process.run()" -b "pdb.gimp_quit(1)"
Alternatively, executing inline Python:
gimp -i --batch-interpreter python-fu-eval -b "import gimp; image=pdb.gimp_file_load('input.png', 'input.png'); pdb.gimp_image_flip(image, 0); pdb.gimp_file_save(image, image.active_layer, 'output.png', 'output.png'); pdb.gimp_quit(1)"
Important AI Execution Considerations
- Always ensure you append
-b '(gimp-quit 0)' (or pdb.gimp_quit(1) in Python) to ensure the GIMP process exits and doesn't infinitely hang the terminal.
- File paths must ideally be absolute, or strictly resolved relative paths to ensure GIMP correctly locates the targets.
