locust

open-source load testing tool written in Python

TLDR

Run load test with web UI

$ locust -f [locustfile.py]

Run headless with specified users and spawn rate

$ locust -f [locustfile.py] --headless -u [100] -r [10] -t [5m]

Specify target host

$ locust -f [locustfile.py] --host [https://example.com]

Run as distributed master

$ locust -f [locustfile.py] --master

Run as distributed worker

$ locust -f [locustfile.py] --worker --master-host [master_ip]

Export results to CSV

$ locust -f [locustfile.py] --headless --csv [results] -u [50] -r [5] -t [2m]

Run with custom web UI port

$ locust -f [locustfile.py] --web-port [8089]

Run specific user classes

$ locust -f [locustfile.py] [UserClass1] [UserClass2]

SYNOPSIS

locust [-f locustfile] [--headless] [-u users] [-r rate] [-t time] [--host url] [options] [UserClass ...]

Locust is an open-source load testing tool written in Python. It allows you to define user behavior in Python code, making tests flexible and version-controllable. Users are simulated as greenlets (lightweight threads), enabling thousands of concurrent users on a single machine.
Tests are defined in a locustfile containing user classes. Each user class defines tasks (HTTP requests or other operations) with optional weights for probability. The @task decorator marks methods as tasks, and between() sets wait times between requests.
The web UI (default port 8089) provides real-time statistics, charts, and controls. You can start/stop tests, adjust user counts, and download results. For CI/CD integration, headless mode runs without the UI.
Distributed mode scales across multiple machines. One master coordinates workers, aggregating statistics and controlling the test. Workers simulate users and report back. This enables millions of requests per second from commodity hardware.
Locust supports custom protocols beyond HTTP through custom clients. The event system allows hooks for custom logging, metrics, and integration with monitoring systems.

PARAMETERS

-f, --locustfile FILE

Path to Python locustfile (default: locustfile.py).

-H, --host URL

Host to load test.

-u, --users NUM

Peak number of concurrent users.

-r, --spawn-rate NUM

Users spawned per second.

-t, --run-time TIME

Stop after specified time (e.g., 300s, 5m, 1h).

--headless

Run without web UI.

--autostart

Start test immediately without waiting.

--autoquit SECONDS

Quit after test completes (headless mode).

--web-host HOST

Host for web interface (default: all interfaces).

--web-port PORT

Port for web interface (default: 8089).

--master

Run as distributed master node.

--worker

Run as distributed worker node.

--master-host HOST

Master node hostname (for workers).

--master-port PORT

Master node port (default: 5557).

--expect-workers NUM

Wait for workers before starting (master only).

--csv PREFIX

Export results to CSV files with prefix.

--html FILE

Generate HTML report.

--json

Output results as JSON.

--loglevel LEVEL

Log level: DEBUG, INFO, WARNING, ERROR.

--exit-code-on-error CODE

Exit code when errors occur.

-L, --list

List available user classes.

CAVEATS

Python-based tests require Python knowledge. Greenlets aren't true threads - CPU-bound tasks block other users. For maximum performance, use multiple worker processes or machines. Web UI should be protected in production environments. Memory usage grows with user count.

HISTORY

Locust was created by Jonatan Heyman starting around 2011 as an alternative to Java-based load testing tools like JMeter. The philosophy was "load testing as code" - using a real programming language rather than XML configuration. Named after the locust swarm metaphor, it gained popularity for its simplicity and the ability to define complex user scenarios in Python. The project is actively maintained with regular releases.