Skip to content

Distributing a Plugin

A plugin is an ordinary Python package. To make a host find it, declare one entry point.

The entry point

The entry-point group is the namespace; the entry-point name is the plugin's name; the value points to the plugin class or @plugin function:

pyproject.toml
[project.entry-points."acme.renderers"]
charts = "acme_charts.plugin:Charts"

Once the package is installed, any host running PluginManager("acme.renderers") finds it, with no change to the host. Entry points are standard packaging metadata, so this works the same with uv_build, hatchling, PDM, setuptools and flit.

A package may provide several plugins, in one namespace or several:

pyproject.toml
[project.entry-points."acme.renderers"]
charts = "acme_charts.plugin:Charts"
maps = "acme_charts.maps:Maps"

[project.entry-points."acme.cli"]
charts = "acme_charts.cli:commands"

Names must agree

The entry-point group must equal the plugin's namespace. A plugin whose namespace differs from the manager's is refused with NamespaceMismatchError, so a misdeclared plugin fails loudly instead of being called by the wrong host.

The entry-point name is the name the host sees (pm.load("charts"), pm.state("charts")). Keep it equal to the plugin's name to avoid confusion.

What discovery costs

Discovery reads the installed packages' metadata and nothing else: the module named in the entry point is imported only when the plugin is loaded. This is what keeps a host's startup cheap with many plugins installed.

Loading imports the module, and whatever it imports at the top level. Keep heavy imports inside load() or inside hooks (Plugin Classes and Functions).

Installed while the host runs

pluxeo does not watch for new packages. A long-running host that wants to pick up a newly installed plugin calls pm.refresh(), then pm.load_all(). See Discovery Modes.

Without entry points

Entry points are the recommended way, but not the only one. A project can ship a generated index instead, or a host can scan a package of its own. See Discovery Modes.