Explicit Plugin Entrypoint

[cyberw]

Discussed in https://github.com/orgs/locustio/discussions/3208

^{Originally posted by ss-bhat September 6, 2025}

✨ Feature Request: --plugins Flag for Explicit Plugin Loading

Problem

Locust is very extensible through events, but today plugins can only be activated by importing them in __init__.py or directly inside locustfile.py.

This has a few drawbacks:

• Plugins are not visible in the CLI.
• Users must remember to add imports manually.
• Many plugins rely on side effects at import time, which can be fragile.

---

Proposal

Add a --plugins flag to the CLI:

locust --plugins=plugin1,plugin2 -f locustfile.py

Locust would import each plugin and call a load(options) function if it exists. This makes plugin activation explicit and avoids side effects.

---

How It Could Work

1. Plugins declare themselves via Python entry points (e.g., in pyproject.toml or setup.py):

   [project.entry-points."locust.plugins"]
   metrics = "locust_metrics_plugin:load"
   tracing = "locust_tracing_plugin:load"

2. At startup, Locust discovers all registered plugins through the locust.plugins entry point group.

3. For each discovered plugin, locust loads the entry point corresponding to the given --plugin

---

Benefits

• Explicit lifecycle: plugins register through load(), no hidden side effects.
• Discoverable: installed plugins can be listed automatically (e.g. locust --list-plugins).
• Cleaner packaging: plugins integrate naturally with Python’s packaging ecosystem.
• Flexible: users can enable multiple plugins in one run by selecting from discovered entry points.

---

Final Note

This is just a proposal. I’d be happy to hear feedback or learn about existing recommended approaches if I’ve missed something. 🙏