locust-plugins fills in the pieces Locust deliberately leaves to you

Why a plugin collection exists next to a bare bones Locust

Locust is described in the project documentation as a bare bones load generation tool, compared with tools such as JMeter or Gatling, and it leaves the user to build even basic functionality such as reading test data from a database or speaking protocols other than HTTP. The author of locust-plugins accepts the first half of that design and objects to the consequence, which is that everyone reinvents the same wheel.

So the package exists to publish one solution to those recurring problems and to collect other people's solutions in the same place. It is maintained by AB SvenskaSpel, with Lars Holmberg named as the author in the package metadata, and the project states plainly that it is separate from Locust core on purpose.

The stated reason for that separation is a trade-off, and it is the most important sentence in the documentation for anyone deciding whether to depend on this package. Keeping the plugins out of core lets them evolve faster, at the cost of being less mature. It also keeps Locust itself from carrying functionality that a given user might not want.

The audience is performance and QA engineers who already know Locust and have hit one of these gaps in their own code. The package is published on PyPI as locust-plugins, and the licence is Apache-2.0.

A second repository in the same organisation, locust-swarm, is mentioned as working well together with these plugins for running distributed load tests.

Listeners that log, chart and act on failure

The listener group covers everything that observes a running test and writes the result somewhere else.

The Timescale listener logs and graphs results using TimescaleDB together with Grafana dashboards, and the repository ships the dashboard definitions alongside the code, with a separate Dashboards section listing command line options such as --timescale, --grafana-url and --pghost. That combination is for teams that want load test results next to their application metrics rather than in Locust's own web UI.

The Jmeter listener writes a jmeter-like output file, which exists for the practical reason that other tools and dashboards read that format. The ApplicationInsights listener writes test logs to Azure Application Insights, and it is listed as an extra alongside the opencensus-ext-azure dependency.

Three listeners in the same group act on failure rather than on results. RescheduleTaskOnFail, ExitOnFail and StopUserOnFail perform actions when a request fails, which is the mechanism for building a test that retries a failing step, halts the run, or takes a user out of the pool.

Each of these is a separate module under locust_plugins with a matching example file under examples/, so you can read a working usage before wiring it into your own locustfile.

User types for Kafka, FTP, Playwright and browsers

The user types are the part of the package that lets a test leave HTTP behind. They live under locust_plugins/users/.

The Playwright user drives a real browser through Playwright, and there is both a plain example and a recording example in the examples directory. The Selenium and Webdriver user covers the other browser automation route, with the webdriver extra pulling in selenium>=4.0.0. An HTTP user that loads the resources of an HTML page is also provided, which is useful when the page under test pulls in scripts and images that a naive request-level test never touches.

The Kafka user generates load against a Kafka topic, backed by the confluent-kafka extra, and the FtpUser covers file transfer with separate upload and download examples. The tn3270 example covers mainframe terminal traffic through the py3270 extra.

A detail worth knowing is what has been removed. The SocketIOUser, the MqttUser and the RestUser used to live here and are now part of Locust core, with the documentation linking to the core pages for each. That is a useful signal about how the boundary moves: functionality that proves broadly useful migrates upstream, and this package keeps the rest.

The plugin also notes that Kafka, MongoDB, Playwright and the dashboards are optional extras rather than default dependencies, so an installation can stay small.

Test data readers, wait times and a transaction manager

Test data handling is covered by the readers group. A CSV reader takes data from a file, with a products.csv example, and a MongoDB reader pulls data from a database using pymongo, with a mongoreader example that also ships ssn.csv and ssn.tsv fixtures. A TSV reader example sits alongside the CSV one.

The wait time group provides custom wait time functions, with a constant_total_ips_ex.py example. The point of this one is to hold a total request rate steady rather than letting a constant think time produce a rate that drifts as the user count changes.

The distributor component supports distributing test data from a master to workers while maintaining test data order. Order is the whole point: when a test has a sequence of dependent steps, each worker has to consume the same data in the same order, which is not what a naive shared queue gives you.

The transaction manager logs transactions, which means aggregating multiple requests or other actions into one recorded unit. Without it, a business transaction spread over five HTTP calls appears in the report as five unrelated requests, and the reported response time tells you nothing about the operation the user actually cares about.

The connection pool component lets users occupy more ports during a test, which the documentation ties to strange load balancer behaviour in low user count, high throughput scenarios.

Installing the package and seeing what it adds to the CLI

Installation is a single pip command, published on PyPI as locust-plugins:

pip install locust-plugins

Most settings are configured from code rather than from the command line, so the practical entry point is the locustfile. Some options are exposed as arguments, and you list them with Locust's regular help argument:

locust --help

The command line options the plugins add are worth knowing by name, because two of them change how a test run ends. An iteration limit, given as -i, stops Locust after a certain number of task iterations, which gives a test a fixed workload rather than a fixed duration. A group of checks, --check-rps, --check-fail-ratio and --check-avg-response-time, produces an error return code when a condition is not met, which is what lets the plugin fail a CI pipeline rather than merely print a red row in the web interface.

The dashboard options --timescale, --grafana-url and --pghost belong to the Timescale and Grafana integration. The examples directory holds a shell script of command line examples, cmd_line_examples.sh, alongside the Python ones.

Extras, packaging metadata and the release cadence

The setup.py file shows the package's dependency structure clearly, and the structure is the main thing to understand before installing it.

Only two packages are required: locust at version 2.35.0 or newer, and typing-extensions. Everything else sits behind extras, one per capability: websocket for websocket-client, playwright for playwright>=1.40.0, dashboards for psycogreen and psycopg2-binary, kafka for confluent-kafka, mongo for pymongo, appinsights for opencensus-ext-azure, resource for lxml, boto3, py3270, and webdriver for selenium>=4.0.0. An all extra installs the full set at once, which is convenient for a workstation and wasteful in a container image.

The package requires Python 3.10 or newer and below 4, and its classifiers list Python 3.10, 3.11 and 3.12 with the development status marked as Beta. The examples directory is excluded from the installed packages, and a py.typed marker is shipped so type checkers pick up the inline annotations.

The development tooling is conventional: black with a line length of 120 configured in pyproject.toml, a tox.ini for the test matrix, mypy.ini for type checking, a .pylintrc, and a Makefile with clean, test, build and release targets, where build produces an sdist with setup.py and release uploads it with twine.

On cadence, the recent versions 5.0.1, 5.0.2 and 5.0.3 were all published on 2026-06-12 within about an hour of each other, and the last push to the master branch is the same day. Batching three versions like that is what a release-preparation session looks like, and it means the version number alone tells you little about how recent a given fix is.

Where the package stops and Locust core takes over

The clearest alternative to this package is writing the missing piece yourself inside your own locustfile, which is the default state for a Locust user. Locust is a programming tool rather than a configuration tool, and the reason the socket and mqtt users were absorbed into core is that the maintainers judged them general enough to maintain centrally.

That boundary is the practical test for any gap locust-plugins fills. If the capability is something most Locust users need, it will probably end up in core, and depending on this package for it means carrying a dependency that later disappears from here. If it is specific, such as a Timescale and Grafana result pipeline, a Kafka user, or the ordered test data distributor, then a community package is the efficient answer and there is no sign of it moving upstream.

The alternative for the cases the project has already handed back is core Locust itself. If you need SocketIO, MQTT or REST-style users today, the documentation points at the core documentation pages rather than at any plugin here, and installing this package will not give you those classes.

For distributed runs there is a second option in the same organisation. locust-swarm is the tool for orchestrating Locust across machines, and this package is described as working well with it, which matters for the distributor and the connection pool components since both assume a master and worker topology.

Editorial conclusion

locust-plugins is the right choice for a performance team that runs Locust against Kafka, FTP, Playwright or browser targets, or that needs Timescale and Grafana result logging without writing its own listeners, and it is the wrong choice for a team needing a stable, vendor-supported component, since the package is classified as Beta and the project states that plugins evolve faster at the expense of maturity. Before adopting it, check the extras in setup.py for the capability you need and install only that extra, then run locust --help to see the plugin command line options Locust exposes.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. SvenskaSpel/locust-plugins on GitHub