locust --master / --worker: Distributed Load
locust --master coordinates the test while locust --worker processes generate the actual requests, so you can push more load than a single Python process allows.
A single locust process is limited by one CPU core because of the GIL. To generate real load in CI you run one master and several workers (often on the same runner), and the master waits for them before starting.
What it does
The --master process owns the UI/CLI, aggregates stats, and controls ramp; --worker processes connect to it and run the tasks. --expect-workers N makes a headless master wait until N workers connect before starting, so the test does not begin under-provisioned.
Common usage
# master (headless, waits for 4 workers)
locust -f locustfile.py --master --headless \
-u 400 -r 40 --run-time 3m --expect-workers 4 &
# 4 workers on the same runner
for i in 1 2 3 4; do
locust -f locustfile.py --worker --master-host 127.0.0.1 &
done
waitOptions
| Flag | What it does |
|---|---|
| --master | Run as the coordinating master |
| --worker | Run as a load-generating worker |
| --master-host <ip> | Where the worker finds the master |
| --master-port <n> | Master bind/connect port (default 5557) |
| --expect-workers N | Master waits for N workers before starting |
In CI
Match -u/-r on the master to the number of workers so each worker gets a sane share, and always set --expect-workers so the ramp does not begin before every worker has registered. Start workers in the background and wait on them so the job does not exit early.
Common errors in CI
Workers logging Failed to connect to master ... Connection refused mean the master is not up yet or --master-host is wrong; start the master first. If the run says Waiting for workers to be ready forever, fewer workers connected than --expect-workers; check the worker logs. Address already in use on port 5557 means a leftover master from a prior step is still bound.