Discovering Plugins with Entry Points in Python CLIs

Your CLI has reached the point where other teams want to add commands to it — a mytool aws group from the cloud team, a mytool billing report from finance engineering — without forking it or sending pull requests to your repository for every change. The standard Python mechanism for this is entry points: a package declares, in its metadata, "I provide something for group mytool.commands called aws, found at mytool_aws.cli:app", and your CLI asks the installed metadata at runtime which providers exist. Installing a plugin is then just pipx inject mytool mytool-aws. This guide builds the host side: declaring the contract, discovering plugins without slowing down startup, mounting them as Typer command groups, keeping one broken plugin from breaking the whole tool, and testing all of it without installing anything. It belongs to the plugin architectures for extensible CLIs topic; the plugin author's side is writing a plugin for an existing CLI.

Prerequisites

• Python 3.10+ (for the importlib.metadata.entry_points(group=...) selection API).
• A Typer or Click CLI with a top-level group.
• A decision about what plugins may provide. This guide uses whole command groups; hook-style plugins are covered in hook-based plugins with pluggy.

How entry points connect host and plugin

A plugin package declares its entry point in pyproject.toml. When it is installed, the declaration is written into the installed distribution's metadata (entry_points.txt in its .dist-info directory). At runtime, the host calls importlib.metadata.entry_points(group="mytool.commands"), which scans installed metadata and returns EntryPoint objects — without importing anything. Only when the host calls ep.load() is the plugin module imported.

The group name is the only thing the host and plugins must agree on, which makes it part of your public API: choose a namespaced name (mytool.commands, not commands), document it, and never rename it.

The recipe: the host

# src/mytool/plugins.py
from __future__ import annotations

import logging
from dataclasses import dataclass
from importlib.metadata import EntryPoint, entry_points

import typer

GROUP = "mytool.commands"
log = logging.getLogger(__name__)


@dataclass
class PluginInfo:
    name: str
    dist: str
    version: str
    error: str | None = None


def discover() -> list[EntryPoint]:
    """Entry points in our group, sorted for stable help output. Imports nothing."""
    return sorted(entry_points(group=GROUP), key=lambda ep: ep.name)


def mount_plugins(app: typer.Typer, builtin_names: set[str]) -> list[PluginInfo]:
    """Load each plugin's Typer app and add it as a command group; never let one break us."""
    report: list[PluginInfo] = []
    for ep in discover():
        dist = ep.dist.name if ep.dist else "?"
        version = ep.dist.version if ep.dist else "?"
        info = PluginInfo(ep.name, dist, version)
        if ep.name in builtin_names:
            info.error = f"name clashes with built-in command {ep.name!r}; skipped"
        else:
            try:
                plugin_app = ep.load()
                if not isinstance(plugin_app, typer.Typer):
                    raise TypeError(f"expected a typer.Typer, got {type(plugin_app).__name__}")
                app.add_typer(plugin_app, name=ep.name)
            except Exception as exc:                        # isolate broken plugins
                info.error = f"{type(exc).__name__}: {exc}"
                log.debug("plugin %s failed to load", ep.name, exc_info=True)
        report.append(info)
    return report

# src/mytool/cli.py
import typer

from mytool.plugins import mount_plugins

app = typer.Typer(no_args_is_help=True)
plugins_app = typer.Typer(help="Inspect installed plugins.")
app.add_typer(plugins_app, name="plugins")


@app.command()
def status() -> None:
    """A built-in command."""
    typer.echo("ok")


BUILTINS = {"status", "plugins"}
PLUGIN_REPORT = mount_plugins(app, BUILTINS)


@plugins_app.command("list")
def plugins_list() -> None:
    """List plugins, their packages and whether they loaded."""
    if not PLUGIN_REPORT:
        typer.echo("no plugins installed", err=True)
    for p in PLUGIN_REPORT:
        state = f"FAILED: {p.error}" if p.error else "ok"
        typer.echo(f"{p.name:<10} {p.dist} {p.version:<10} {state}")


def main() -> None:
    for p in PLUGIN_REPORT:
        if p.error:
            typer.echo(f"warning: plugin {p.name!r} ({p.dist}) not loaded: {p.error}", err=True)
    app()


if __name__ == "__main__":
    main()

The decisions that matter

Discovery is cheap; loading is not. entry_points() reads small metadata files. ep.load() imports the plugin and everything it imports — possibly a cloud SDK. This version loads every plugin at startup because Typer needs the command groups to build help. If plugins are heavy, register a lazy group instead, loading a plugin only when its name is invoked; the technique is in lazy-loading subcommands for faster startup and building dynamic commands in Click.

One broken plugin must not break the tool. A plugin built against an older version of your API may fail to import. Catching the error, recording it, and warning on stderr keeps every other command working — including plugins list, which is exactly what the user needs to diagnose the problem.

Built-ins win name clashes. A plugin called status would otherwise silently replace a built-in command. Reserving built-in names makes the host's own interface stable.

Validate the type. Checking that the loaded object is a typer.Typer turns a confusing downstream error into a clear message naming the plugin.

Report the providing package. ep.dist gives the distribution that declared the entry point, so errors and plugins list say which package to upgrade or remove.

The plugin side, briefly

A plugin package needs only a Typer app and one entry in its pyproject.toml:

# mytool-aws/pyproject.toml
[project]
name = "mytool-aws"
version = "2.1.0"
dependencies = ["mytool>=3.0,<4", "boto3>=1.34"]

[project.entry-points."mytool.commands"]
aws = "mytool_aws.cli:app"

Users install it alongside the host: pipx inject mytool mytool-aws or uv tool install mytool --with mytool-aws. The plugin must be in the same environment as the host, which is why plain pipx install mytool-aws (a separate environment) does not work — a common support question worth answering in your documentation.

Trust and safety

Loading a plugin runs its code with the same permissions as your CLI, which usually means the user's credentials and filesystem. Entry-point discovery loads every installed package that declares your group, so it is worth being deliberate about trust:

• Plugins are code the user chose to install. That is the same trust model as any Python dependency, and it is appropriate for most internal tools. Say so in the documentation so nobody assumes plugins are sandboxed.
• Offer a way to disable them. A --no-plugins flag or MYTOOL_DISABLE_PLUGINS=1 environment variable lets users rule plugins out when debugging, and lets security-sensitive automation run only built-in code.
• Allow an allow-list in config. plugins.enabled = ["aws"] in the user's config limits loading to named plugins, which is useful in shared environments where many packages are installed.
• Never load plugins from the current directory or project files. Discovery through installed metadata only is what keeps a cloned repository from injecting code into your tool.

UX considerations

• Make plugins visible. mytool plugins list answers "is it installed?" and "which version?", the first two questions in any plugin support thread.
• Warn once, briefly. A failing plugin warning on every invocation is irritating but important; keep it to one line and point at mytool plugins list for detail.
• Document installation per installer. Show the exact commands for pipx (inject), uv (--with) and plain virtual environments.
• Group plugin commands in help. Typer's rich_help_panel parameter on add_typer can put plugin groups in their own "Plugins" section of --help, so users can tell built-ins from extensions.

Testing the behaviour

You do not need to build and install real packages to test discovery. EntryPoint objects can be constructed directly, pointing at modules in your test suite, and entry_points can be patched to return them:

# tests/test_plugins.py
import sys
import types
from importlib.metadata import EntryPoint

import typer
from typer.testing import CliRunner

from mytool import plugins


def make_module(name: str, **attrs) -> None:
    mod = types.ModuleType(name)
    mod.__dict__.update(attrs)
    sys.modules[name] = mod


def fake_entry_points(monkeypatch, *eps: EntryPoint) -> None:
    monkeypatch.setattr(plugins, "entry_points", lambda group: [e for e in eps if e.group == group])


def test_plugin_is_mounted(monkeypatch):
    plugin_app = typer.Typer()

    @plugin_app.command()
    def deploy() -> None:
        typer.echo("aws deploy!")

    make_module("fake_aws", app=plugin_app)
    fake_entry_points(monkeypatch, EntryPoint("aws", "fake_aws:app", plugins.GROUP))
    host = typer.Typer()
    report = plugins.mount_plugins(host, builtin_names=set())
    assert report[0].error is None
    result = CliRunner().invoke(host, ["aws", "deploy"])
    assert "aws deploy!" in result.output


def test_broken_plugin_is_isolated(monkeypatch):
    fake_entry_points(monkeypatch, EntryPoint("bad", "does_not_exist:app", plugins.GROUP))
    report = plugins.mount_plugins(typer.Typer(), builtin_names=set())
    assert report[0].error.startswith("ModuleNotFoundError")


def test_builtin_names_are_protected(monkeypatch):
    fake_entry_points(monkeypatch, EntryPoint("status", "fake_aws:app", plugins.GROUP))
    report = plugins.mount_plugins(typer.Typer(), builtin_names={"status"})
    assert "clashes" in report[0].error

For a full end-to-end check, a small plugin package in tests/fixtures/ installed into a temporary environment proves that real metadata is discovered — worth one slow test in CI, following end-to-end testing an installed CLI.

Conclusion

Entry points give a Python CLI a plugin system with no registry, no configuration and no custom loader: plugins declare themselves in their metadata, and the host discovers them with one standard-library call. Name the group carefully and treat it as public API, discover cheaply and load deliberately, mount plugins as command groups, isolate failures so one bad plugin cannot take the tool down, protect built-in names, and show users what is installed. Tests can fake entry points directly, so the whole mechanism is testable in milliseconds.

Frequently asked questions

Related

• Up: Plugin architectures for extensible CLIs
• Writing a plugin for an existing CLI
• Hook-based plugins with pluggy
• Versioning a plugin API
• Writing pyproject.toml metadata for a CLI