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:
Dispatcharr makes this available to the application and Celery workers as:
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¶
- Open Plugins in Dispatcharr.
- Reload plugins after creating or changing local plugin files. The plugin list uses cached discovery and does not automatically rescan copied or removed folders.
- Open My Plugin, review its settings, and enable it.
- 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¶
- Define settings in Plugin settings fields, and review actions and manifest versions in Plugin manifest and capabilities.
- Learn about events and long-running work in Runtime, events, and background work, and durable data in Plugin storage and lifecycle.
- Validate and package the plugin in Test and package a plugin.