GIMP 3 Python Enums: Definitive Plug-in and Script-Fu Guide

Applications
,
1

If you’re developing Python plug-ins or Script-Fu scripts for GIMP 3, you’ll know the frustration of tracking down correct enum values. The official API docs are written for C developers, leaving Python authors to piece things together from source code, forum posts, and trial and error.

I’ve put together what I hope is the definitive reference: every enum available in GIMP 3.0, compiled directly from a live GIMP 3.0.8 instance using a Python-Fu console script. That means the values are guaranteed accurate for that version. And the script is available as a free download so you can regenerate the complete listing for any future GIMP 3 release.

Each enum includes:

  • the Python form you actually use in your plug-ins (e.g. Gimp.LayerMode.NORMAL)

  • the uppercase PDB identifier, most useful when cross-referencing with the C API docs or porting code from GIMP 2.x Script-Fu scripts

  • the raw integer value for legacy Script-Fu work

  • the GEGL nickname for serialisation.

The Gimp.LayerMode table also includes the full GEGL operation string.

Every enum has a plain-English description written specifically for Python and Script-Fu developers.

https://www.chuckhenrich.com/gimp-3-python-enums-complete-reference/

Comments/suggestions welcome.

1 Like
2

The official API docs are written for C developers, leaving Python authors to piece things together from source code, forum posts, and trial and error.

Indeed!

Your list was probably a lot of work. Thanks for doing this.

1 Like
3

It is true, though the logic to retrieve the Python syntax from the C one is well defined. So once you are used to it, I find it not really much of a problem anymore. At least I personally don’t have much problem finding these enum values in Python by reading the C docs. :wink:

This being said, our developer website has a link to a third-party API docs targetted at the Python syntax. See there: Reference for GIMP 3.0 API – GIMP Developer (the same link where you probably also found the C docs; but below the C API docs, you’ll find other links named “GIMP library for Python”; and the same for the GIMP UI lib)

You’ll find all the enums (and more!) there, using the Python syntax.

Some small additional notes:

Though the integer values won’t change for the whole duration of the v3 series (as the API is stable), I would really advise against using integer values in Script-Fu!

All the libgimp enum types are introspected and recreated in Script-Fu too! For instance, don’t use 28 instead of GIMP_LAYER_MODE_NORMAL! Use LAYER-MODE-NORMAL directly in your script. This makes for semantic names and therefore much more readable code.

Unless you just meant using it to port old script-fu scripts to newer API!

the GEGL nickname for serialisation.

What is this and what is this for exactly?

In any case, nice job! :+1:

4

Thanks!

Serialisation in this context means saving settings to a file or config in a text-based format — for example, when GIMP saves an XCF file, a script, or a preset, it needs a stable text identifier for each enum value rather than just a number.

The GEGL nickname is that stable text identifier. So instead of storing the integer 28 for a layer’s blend mode, GIMP writes the string normal. This makes the saved file human-readable and more robust across versions, since integer values could theoretically change but the nickname is intended to stay stable.

In practice, most Python plug-in developers never need the GEGL nickname directly — you use the Python enum form in your code. The nickname is more relevant if you’re working directly with GEGL operations, parsing XCF or config files, or doing serialisation work yourself.

I was aware of that resource but the name and layout confused me. There’s nothing on that page or in the URL that identifies it as official GIMP 3 API. The site title “PyGObject API Reference” doesn’t reference GIMP. The URL looks pretty unofficial, and with a massive number of other APIs listed, I didn’t have faith that it was up-to-date and complete. So I rolled my own enum reference using GIMP’s built in functionality, to be sure I was getting the complete, official picture.

With GIMP 3’s major improvements (it really is great), it’s to be expected more and more people like me will dive into plug-in development. And with the rise of vibe coding especially, it’s crucial to be sure that references are clearly marked as official and up-to-date, so devs can find and use them confidently and point their AI helpers (if any) to transparently correctly compiled references.

I have a lot (decades!) of experience in technical writing, among other things. I’d be happy to volunteer to help out with that.

5

No it can’t. Our API is meant to be completely stable and we won’t ever change the enum values, at least within a same major series. But even if it were to happen in a major bump, say in GIMP 4 (but really, it won’t for such important values like layer modes, because this would be a headache), we would have conversion code anyway. The ability to never break any past XCF is also one of our top priorities, and considered a feature of GIMP (you should still be able to open a XCF from 30 years ago and it should render the same).

If ever you see an integer value change for a given enum value, within the whole GIMP 3.x series, please report it. It will be a bug.

We still advise to use enum values because that’s semantically much better and creates more readable hence maintainable code. But the integer values are stable nonetheless.

Not in XCF for sure. Look the PROP_MODE propertly in the XCF specs. We store the values as int.

Now it’s true that we use more readable names in various config files. Note though that these formats are not meant to be stable though. Config file formats may change at various points in time (during minor version updates). We still care a lot about not breaking people’s config of course, so GIMP will automatically migrate config files to new formats when this happens. But we don’t guarantee that a file format will stay the same and will use the same syntax, because it is not meant to be edited by hand (it can be! That is the advantage of having readable config files; but that’s a bonus, not a guarantee).

Anyway, it’s not a problem to have this info on your website. But I wouldn’t consider it part of the official (stable) API (even though I doubt this will change any time soon). :sweat_smile:

I was aware of that resource but the name and layout confused me. There’s nothing on that page or in the URL that identifies it as official GIMP 3 API. The site title “PyGObject API Reference” doesn’t reference GIMP. The URL looks pretty unofficial, and with a massive number of other APIs listed, I didn’t have faith that it was up-to-date and complete.

The webpage itself is not official, but as far as we know, it is generated off our GObject-Introspection data. I’m not sure how often it is updated, but since it says “Gimp 3.0 (3.2.0)” at the top, I am guessing it uses development code. I don’t see some of the latest API updates from the main source repository but I see new API from 3.2.0 RC1. So it might use tags on the main repository, or maybe dev tarballs. :person_shrugging:
It’s quite recent at least.

The contributor who maintains this list of introspected APIs is a major contributor of the MSYS2 project.

Yeah anyway whatever exists, doing your own thing is never lost work, nor is it bad. :slight_smile:

Contributions are always welcome. We revived the development website a few years and are slowly adding new documentation, both for core developers or for third-party developers who will develop plug-ins with libgimp.

Help in improving tutorials, etc. is appreciated.

6

You’re welcome! Yes it was a lot of work but worth it, I learned a lot. And I’m using it a lot too.