Locust Command‑Line Parameters and Script Configuration Guide

When you start a load test with the locust command, a variety of command‑line arguments can be used to control the test execution.

Key options include:

-f, --locustfile: specify the Locust file (default
locustfile.py
)
locust -f my_locustfile.py
--headless: run without the web UI, suitable for CI/CD pipelines
locust -f my_locustfile.py --headless -u 100 -r 10 -t 1m
-u, --users: total number of concurrent users
-r, --spawn-rate: users spawned per second
-t, --run-time: duration of the test (e.g., 1h30m)
--host: target host URL
--web-host: IP address for the Web UI (default 127.0.0.1)
--web-port: port for the Web UI (default 8089)

Beyond command‑line arguments, you can configure behavior directly inside a Locust script.

wait_time attribute defines the pause between tasks; it can be a fixed value, a range, or a custom function.

from locust import HttpUser, task, between
class WebsiteUser(HttpUser):
wait_time = between(1, 5)  # random wait between 1 and 5 seconds

tasks attribute specifies the set of tasks a user performs, and you can assign weights to influence selection probability.

@task(3)  # three times more likely than unweighted tasks
def high_priority_task(self):
pass
@task(1)
def low_priority_task(self):
pass

Locust uses HttpSession as the default client, but you can create a custom client to support other protocols or special requirements.

from locust import HttpUser, task
class MyUser(HttpUser):
def __init__(self, *args, **kwargs):
super(MyUser, self).__init__(*args, **kwargs)
# initialize custom client here

Additional useful configurations include catch_response to manually mark a request as success or failure, and the on_start / on_stop methods that run when a virtual user begins or ends, useful for setup and teardown.

with self.client.get("/", catch_response=True) as response:
if response.content.decode() != "expected content":
response.failure("Content did not match")
def on_start(self):
"""User initialization"""
pass
def on_stop(self):
"""User cleanup"""
pass

These features represent only a subset of Locust's capabilities; by combining them you can accurately simulate real user behavior and conduct effective load testing of your systems.