Skip to content

Plugin development quick start

Documentation version

Last updated against Dispatcharr v0.34.x, commit f58a82ce.

Changes made after this commit, including unreleased changes, may not yet be reflected in these pages.

A Dispatcharr plugin is a directory containing a plugin.json manifest and Python code that exports a Plugin class. This guide creates a minimal plugin with one action and two settings.

For manifest, field, action, and capability guidance, see Plugin manifest and capabilities.

Create the plugin directory

In a standard Compose installation, create a directory on the host:

data/plugins/my-plugin/

Dispatcharr makes this available to the application and Celery workers as:

/data/plugins/my-plugin/

DISPATCHARR_PLUGINS_DIR overrides the runtime plugin directory.

Add the manifest

Create data/plugins/my-plugin/plugin.json:

{
  "manifest_version": 2,
  "name": "My Plugin",
  "version": "0.1.0",
  "description": "A minimal Dispatcharr plugin",
  "capabilities": [],
  "fields": [
    {
      "id": "enabled",
      "label": "Enabled",
      "type": "boolean",
      "default": true
    },
    {
      "id": "note",
      "label": "Note",
      "type": "string",
      "default": ""
    }
  ],
  "actions": [
    {
      "id": "run",
      "label": "Run"
    }
  ]
}

New plugins should declare manifest_version: 1 or later. Manifest version 2 or later is recommended because it enables Dispatcharr's supported runtime capability checks. This example needs no additional capabilities.

Why use a manifest?

Dispatcharr can read a valid manifest while the plugin is disabled, so it can display metadata, settings, actions, and capability requests without importing plugin code.

Add the plugin code

Create data/plugins/my-plugin/plugin.py:

class Plugin:
    def run(self, action: str, params: dict, context: dict):
        if action == "run":
            settings = context["settings"]
            return {
                "status": "ok",
                "enabled": settings.get("enabled", True),
            }

        return {
            "status": "error",
            "message": f"Unknown action: {action}",
        }

Dispatcharr loads the Plugin class from plugin.py. A package may export the class from its __init__.py instead. If both are present, Dispatcharr uses plugin.py.

A manifest alone is not enough for discovery: the plugin directory must contain plugin.py or __init__.py.

The action ID passed to run() matches the action declared in plugin.json. context["settings"] contains the saved values for fields in the manifest.

For manifest version 2 or later, declare actions in plugin.json; Python-only action definitions are not available. Settings fields can instead be provided in Python, although manifest fields let Dispatcharr display them while the plugin is disabled. See Plugin settings fields.

Load and enable the plugin

  1. Open Plugins in Dispatcharr.
  2. Reload plugins after creating or changing local plugin files. The plugin list uses cached discovery and does not automatically rescan copied or removed folders.
  3. Open My Plugin, review its settings, and enable it.
  4. Run Run from the plugin detail page.

New plugins are disabled by default. Plugins that declare capabilities must be acknowledged before they can be enabled.

Next steps