Hacking:Plugins v3

From GIMP Developer Wiki
Revision as of 11:50, 13 July 2020 by Bootchk (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

This describes Gimp 3 plugins. For Gimp 2, see Hacking:Plugins. Much of what is written there still applies.


Gimp version 3 supports plugins using GObject Introspection (GI).

See an example below.

A GIMP Python plugin:

  • imports the PyGObject module using "import gi" and imports the GIMP bindings
  • inherits the class Gimp.PlugIn
  • implements the virtual methods do_query_procedures(self) and do_create_procedure(self)
  • implements the meat of the plugin in a "run procedure" of any name, registered with GIMP
  • calls Gimp.main()

Similarly for other languages?


Just as in Gimp version 2, there is:

  • a full API for writing a plugin
  • and a simplified GimpFu API.

GimpFu has not been ported yet, but there is an effort to port it.

The full API is more complex than the GimpFu API. It exists now.

Other notes about GIMP 3 plugins

In version 2, PyGimp/GimpFu (and ScriptFu, etc.) did these things:

  • saved the "default" control values for a plugin so that it could be run again with the previous values
  • implemented a plugin's control panel GUI from a declarative specification

In version 3, these things will be done by GIMP itself (and thus available to all languages.) However, as of this writing, they are not quite ready.

Backward compatibilility

When GimpFu is ported, existing version 2 plugins will require minor changes:

  • for Python 3 syntax and standard module changes
  • some deprecated GIMP procedures might become obsolete
  • miscellaneous changes

Language bindings

Any language that supports GI can be used.

There are examples for the languages: C, Python, Scheme, Lua, and Javascript

Example code

In the GIMP repository, see gimp/plug-ins/goat-exercises. A "goat-exercise" is a demo. There is one for each language binding.

For Python language examples, also see gimp/plug-ins/python.

Generating documents for language bindings

Use the g-ir-doc-tool, available for example in the developer package gobject-introspection.

This example creates a yelp browsable document for the Python binding to Gimp, in your home directory:

    g-ir-doc-tool --language=Python -o ~/gimp-doc /usr/local/share/gir-1.0/Gimp-3.0.gir

The .gir file might be installed with GIMP, or might require building GIMP. Or GIMP 3 might ship with the documents already generated.

Other .gir files should be installed with your distribution, in /usr/share/gir-1.0 :



A plugin that implements a compute intensive image processing algorithm should probably be implemented in C as a GEGL plugin.

A plugin that is a simple recipe for calling a sequence of GIMP procedures, or that otherwise simplifies a GIMP user's life, can be written in the high-level scripting language of your choice.


-- Passing native sequence types e.g. list for GIMP array types --

In a binding, where it specifies a length and a native sequence, use just a native sequence in the call. For example if the binding specifies (..., int, [float]), pass only a list of floats. In other words, there is a discrepancy in the count of formal arguments as specified for the binding, and the count of actual arguments passed. The language binding performs magic in converting a native sequence like list to the two GObjects (int and "array") that GIMP wants.


In version 2:

  • PyGimp was a set of modules implementing the full API and other niceties
  • GimpFu was a single module that implemented the simplified API, but imported some niceties from PyGimp
  • PythonFu was used as a prefix of names of plugins using Python, and also to refer the the Python console