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

[ss-bhat]

✨ 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. 🙏

[cyberw]

I think this is super interesting. I basically had to ”hack” locust-plugins into locust core by adding a import-for-side effects, and I’ve always wanted to do it nicer.

I think your approach makes sense.

Just one question: With pytest support integrated into locust (since the latest release) is there a ”pytest” way to do this, perhaps we can use that?

[ss-bhat]

Thanks for the feedback 🙏 — you’re right, what I’m suggesting is basically the same kind of plugin architecture that pytest uses.

From a Locust perspective I was imagining:

• plugins declare themselves via entry points (locust.plugins group),
• Locust discovers them at startup,
• users can enable them with a --plugins (or -p) flag,
• plugins are loaded in the order given,
• and if no --plugins flag is provided, then nothing is loaded automatically (to keep things explicit and avoid confusion about event firing order).

My understanding (I might be wrong!) is that pytest loads all discovered plugins by default and you can disable them with -p no:plugin. My suggestion was more of an explicit opt-in model.

Either way could work — pytest’s style would feel familiar to many users, but I personally like the clarity of requiring explicit activation.

[ss-bhat]

Rough Idea:

I think it would make sense to load plugins right after this line.

locust/locust/main.py

Line 175 in 1144476

locustfiles = get_locustfiles_locally(options)

That way, all plugin event handlers are registered first, and then the event handlers defined in locustfile.py are attached afterwards. This ensures that user-defined handlers in the locustfile run after any plugin logic, which makes the event order easier to understand.

[cyberw]

I think we can go ahead and enable installed plugins by default and have an opt-out model like pytest. 999/1000 times if a user has a plugin installed they'll wanna enable it :)

Other than that your approach looks great!

[ss-bhat]

I agree that enabling installed plugins by default with an opt-out model will work well for most users. ✅

Just thinking out loud—since Locust is event-driven, the order in which plugins load can matter? For example, if plugin2 depends on plugin1, it might be helpful to explicitly define the load order to avoid any unexpected behavior.

Some good reference on how plugins and its order are handled in CKAN

[cyberw]

I guess ordering could matter in some cases, but it should be very rare, and because plugins can add themselves to locust init event, they can delay loading if necessary. I think it is not a major concern. Also, I don't think we'll suddenly have more than a couple commonly used plugins :)

[ss-bhat]

Perfect, thank you for the clarification and support! 😊
I’m actually working on a plugin myself, so your insights are very helpful. Appreciate it!

[cyberw]

Looking forward to your PR :) I'll convert this conversation into an issue so it can be tracked.