How to package a plugin that will work on Flatpak

Special actions need to be taken in order for plug-ins work on the Linux Flatpak version of GIMP. Specifically, they should be packaged as an “extension”. This is due to Flatpak’s sandboxing and design, for example. From start, they needs:

org.gimp.GIMP.Plugin*.json
org.gimp.GIMP.Plugin*.metainfo.xml (if the plug-in source code does not have one)
Plug-in source code in a remote repository or server

Configuring the ’extension’ manifest

The Flatpak package that we will create isn’t an app one but an extension package, which should have the following manifest contents:

org.gimp.GIMP.Plugin*.json

{
    "id": "org.gimp.GIMP.Plugin.PLUG-IN-NAME-WITHOUT-SYMBOLS-OR-SPACES",
    "branch": "MAJOR",
    "runtime": "org.gimp.GIMP",
    "runtime-version": "stable",
    "sdk": "org.gnome.Sdk//SDK-VERSION",
    "build-extension": true,
    "build-options": {
        "prefix": "/app/extensions/PLUG-IN-NAME-WITHOUT-SYMBOLS-OR-SPACES",
        "prepend-path": "/app/extensions/PLUG-IN-NAME-WITHOUT-SYMBOLS-OR-SPACES/bin",
        "prepend-pkg-config-path": "/app/extensions/PLUG-IN-NAME-WITHOUT-SYMBOLS-OR-SPACES/lib/pkgconfig",
        "prepend-ld-library-path": "/app/extensions/PLUG-IN-NAME-WITHOUT-SYMBOLS-OR-SPACES/lib"
    },
    "modules": [
        {
            "name": "PLUG-IN-NAME-WITHOUT-SYMBOLS-OR-SPACES",
            etc...
        }
    ]
}

Change MAJOR to the GIMP API version your plugin supports, which should correspond to “add-extensions”.“org.gimp.GIMP.Plugin”.“version” on GIMP flatpak manifest. SDK-VERSION should correspond to “runtime-version”. Then, set the PLUG-IN-NAME-WITHOUT-SYMBOLS-OR-SPACES accordingly and configure the modules section following your build needs.

Creating the AppStream metadata

The only asset needed by an extension package is the AppStream metadata. You can create it, if your plug-in does not have one, with the following content:

org.gimp.GIMP.Plugin*.metainfo.xml

<?xml version="1.0" encoding="UTF-8"?>
<component type="addon">
  <id>org.gimp.GIMP.Plugin.PLUG-IN-NAME-WITHOUT-SYMBOLS-OR-SPACES</id>
  <extends>org.gimp.GIMP</extends>
  <name>PLUG-IN-NAME</name>
  <summary>PLUG-IN-NAME GIMP Plugin</summary>
  <description>
    <p>PLUG-IN-DESC</p>
  </description>
  <url type="homepage">PLUG-IN-REPO-URL</url>
  <metadata_license>PLUG-IN-LICENSE</metadata_license>
  <project_license>PLUG-IN-LICENSE</project_license>
  <releases>
    <release date="PLUG-IN-RELEASE-DATE" version="PLUG-IN-RELEASE-VERSION"/>
  </releases>
</component>

This does not aim to replace Flathub nor AppStream documentation. Complete info can be found on: https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines

Packaging the .flatpak

Continuing, in the manifest folder, build and package the plug-in this way:

flatpak-builder --force-clean --disable-rofiles-fuse --keep-build-dirs --repo=repo "$PWD/_install" org.gimp.GIMP.Plugin*.json
flatpak build-bundle --runtime repo org.gimp.GIMP.Plugin.PLUG-IN-NAME-WITHOUT-SYMBOLS-OR-SPACES.flatpak --runtime-repo=https://dl.flathub.org/repo/flathub.flatpakrepo org.gimp.GIMP.Plugin.PLUG-IN-NAME-WITHOUT-SYMBOLS-OR-SPACES MAJOR

Now, if necessary, test the package installing it:

flatpak install --user org.gimp.GIMP.Plugin.PLUG-IN-NAME-WITHOUT-SYMBOLS-OR-SPACES.flatpak

Distributing with Flathub

Typically, your plugin may continue to get new features and bug fixes. And the easiest way to ensure this for the users is to distribute it on Flathub, the same repository that distributes GIMP Flatpak.

Take a look at the Flathub submission guidelines

Last updated on October 16, 2025

How to package a plugin that will work on Snap