Skip to content

Using plugins (consumer guide)

How to install, enable, and review third-party Hedron plugins in an application. To write a plugin, see Plugin authoring and the Plugins API.

Defaults

[tool.hedron].plugins Behavior
omit / unset Discover and load all hedron.plugins entry points
[] Load none (deny-by-default)
["name", …] Load only those plugin names; missing names raise HED-PLUGIN-MISSING

Production apps that do not intentionally use plugins should set plugins = [].

pyproject.toml
[tool.hedron]
plugins = []   # deny-by-default until you review a plugin

Full key table: Configuration.

Install a plugin distribution

  1. Add the package to your environment (same train pin as Hedron when possible):
pip install "hedron-sample-kit>=0.1.0,<0.2"
# or: uv add "hedron-sample-kit>=0.1.0,<0.2"
  1. Enable it by name (the entry-point key, not the PyPI distribution name):
[tool.hedron]
plugins = ["sample_kit"]
  1. Restart the app. Incompatible hedron_version ranges fail at load (HED-PLUGIN-0002) and roll back that plugin’s contributions — they do not silently no-op.

Review before enablement

Third-party plugins are out of Hedron’s security scope until you review them (enterprise diligence, threat model).

Checklist:

  • Pin the plugin distribution; prefer packages that declare hedron_version for your train
  • Prefer local package assets over remote script/URL loads
  • Inspect registered components, Explorer panels, and diagnostic prefixes
  • Run hedron check / Explorer locally with explorer="development" before production
  • Keep production explorer="off" (or secured with real auth)

Troubleshooting

Symptom Fix
Plugin components missing Confirm install + plugins allowlist name matches the entry point
HED-PLUGIN-MISSING Name in plugins = [...] not discovered — install package or fix spelling
Load rejected / rolled back Check hedron_version compatibility and contribution validation errors
Unexpected panels in Explorer You are loading all entry points — set an explicit allowlist or []

See also

Plugin authoring · Plugins API · hedron-sample-kit