Skip to content

Scripting: Plugins

Plugins go in the plugins data directory, each plugin must have its own sub-directory and a plugin.json file that describes the plugin.

The plugin will be identified by the name of the directory it's in.


This file describes the plugin and its functionality.

It's a JSON file with the following keys:

namestringName shown in the list of plugins. If omitted it will be the plugin id.
descriptionstringLonger description of what the plugin does.
versionnumberPlugin version number, used to resolve multiple installations of the same plugin
engineRequiredstringScript engine to use. (Currently must be python)
authorstringName of the plugin author.
iconstringSee Icons
servicesRequiredarrayArray of services.


icon fields can use a file name relative to the plugin directory:

    "icon": "my_icon.svg"

If the field value starts with "theme:" it will load an icon from the icon theme:

    "icon": "theme:image-gif"

Theme icons follow the Freedesktop icon naming specs.

There are also several icons not in the specs available in the default theme, you can use this icon searcher to find them.


A service is defined ad a JSON object, which must have a type field and additional fields based on the service type.


Action services show an entry on the "Plugins" menu, and are triggered when the user clicks on one of the actions.

The service JSON object has the following fields:

scriptRequiredobjectScript object to execute
labelstringText shown in the menu
tooltipstringMenu item tooltip
iconstringSee Icons

The script function will be invoked with these arguments:

  • The application window
  • The open document
  • A dict with the settings values.


Format services services add support for opening and saving to more file formats.

They will be visible in the open and save dialogs.

The service JSON object has the following fields:

namestringText shown in the dialog
openobjectScript object to execute on open
saveobjectScript object to execute on save
extensionsRequiredarrayArray of file extensions (without the dot)
slugstringFormat identifier, defaults to the first value in extensions
auto_openboolIf set to false, the file will not be opened before the plugin invocation

At least one between open and save must be present.

open and save will be invoked with the following arguments:

  • The application window
  • The document to read from / write into
  • A file-like object to perform io operations on
  • The name of the file
  • An ImportExport object to report back
  • A dict with the settings values


A plugin script is defined as a JSON object that provides information on how to run the plugin.

It has the following fields:

moduleRequiredstringPython module to load
functionRequiredstringFunction within module to execute
settingsobjectSettings object


Settings provide parameters to pass the invoked function. The user will be shown a dialog with all these settings before the script execution.

If you need more advanced control over the dialog, see the dialog example.

They are defined as a JSON array os settings objects:

nameRequiredstringName, will be used as dict keys for values
typeRequiredstringSetting type
labelstringForm label (defaults to the setting name)
descriptionstringExtra description
default(any)Default value for the setting
minnumberMinimum value (for int and float)
maxnumberMaximum value (for int and float)
choicesarrayAvailable choices (for choice)

Setting types

  • info Just displays the description without any input.
  • bool Shows a checkbox.
  • int Shows a spin box.
  • float Shows a spin box.
  • string Shows a line edit.
  • choice Shows a combo box.


Example file structure:


The above plugin will have an ID of MyPlugin.


    "name": "Hello World Plugin",
    "description": "Shows a greeting",
    "author": "Glax",
    "engine": "python",
    "services": [
            "type": "action",
            "label": "Hello world",
            "tooltip": "Does nothing useful",
            "script": {
                "module": "hello_world",
                "function": "main",
                "settings": [
                        "name": "greeting",
                        "label": "Type a greeting:",
                        "type": "string",
                        "default": "Hello World"

def main(window, document, settings):