The most surprising thing about Locust’s environment configuration is that locust --help doesn’t actually show you all the ways you can configure it.
Let’s say you’re running a load test and want to control some parameters. You’ve got your locustfile.py with your user behavior:
from locust import HttpUser, task, between
class WebsiteUser(HttpUser):
wait_time = between(1, 5)
@task
def index(self):
self.client.get("/")
@task
def about(self):
self.client.get("/about")
You can run this with locust -f locustfile.py. But what if you need to change the number of users, the spawn rate, or the host?
Controlling the User Count and Spawn Rate
The most common way to adjust the test is by specifying the number of users and how quickly they should start. You can do this directly on the command line.
To start with 100 users, spawning at a rate of 20 users per second:
locust -f locustfile.py --users 100 --spawn-rate 20
This tells Locust to gradually ramp up to a total of 100 concurrent users, adding 20 new users every second until the target is reached.
Setting the Target Host
If your locustfile.py doesn’t define a host attribute, or if you want to override it for a specific test run, you can use the --host flag.
For example, to test a staging environment at http://staging.example.com:
locust -f locustfile.py --host http://staging.example.com --users 50 --spawn-rate 10
This is incredibly useful for targeting different environments without modifying your locustfile.py itself. Locust will prepend this host to all requests made by self.client.
Running in Headless Mode
For automated testing or CI/CD pipelines, you’ll want to run Locust without the web UI. This is called headless mode.
To run a test for 5 minutes (300 seconds) with 200 users, spawning at 50 users per second, and then exit:
locust -f locustfile.py --headless --users 200 --spawn-rate 50 --run-time 5m
The --run-time parameter accepts values like 20s, 10m, 1h. When the specified time elapses, Locust will stop spawning new users and wait for existing users to finish their current tasks before exiting.
Specifying the Web UI Host and Port
By default, the Locust web UI runs on http://localhost:8089. You can change this if needed.
To run the web UI on port 8000 and accessible from any IP address (use with caution!):
locust -f locustfile.py --web-host 0.0.0.0 --web-port 8000
This is helpful if you’re running Locust on a remote server and want to access the UI from your local machine, or if port 8089 is already in use.
Controlling Logging and Verbosity
Locust can be quite chatty. You can control its logging level.
To see more detailed debug information:
locust -f locustfile.py --loglevel DEBUG
Common log levels include DEBUG, INFO, WARNING, ERROR, and CRITICAL. DEBUG will show you everything, including detailed request/response information and internal Locust events.
The Invisible Configuration: Environment Variables
Beyond command-line flags, Locust can also be configured using environment variables. This is less commonly known but powerful for scripting and deployment.
For instance, to set the number of users and spawn rate via environment variables:
export LOCUST_USERS=500
export LOCUST_SPAWN_RATE=100
locust -f locustfile.py
In this case, Locust will pick up LOCUST_USERS and LOCUST_SPAWN_RATE directly. This convention extends to many other flags: LOCUST_HOST, LOCUST_RUN_TIME, LOCUST_HEADLESS, LOCUST_LOGLEVEL, and even LOCUST_WEB_HOST/LOCUST_WEB_PORT.
The order of precedence for configuration is: environment variables > command-line flags > defaults.
Advanced Configuration: The Environment Object
For more complex scenarios, you can programmatically configure Locust within your locustfile.py itself using the Environment object. This allows you to dynamically adjust settings based on external factors or complex logic.
Here’s a snippet showing how you might initialize Locust with specific settings:
from locust import HttpUser, task, between
from locust.env import Environment
from locust.stats import stats_printer, stats_history
from locust.runners import LocalRunner
import gevent
class WebsiteUser(HttpUser):
wait_time = between(1, 5)
@task
def index(self):
self.client.get("/")
# --- Programmatic Configuration ---
env = Environment(user_classes=[WebsiteUser])
runner = LocalRunner(env)
# You can then set attributes on the runner or env
# runner.target_user_count = 100
# runner.spawn_rate = 20
# env.host = "http://api.example.com"
# For programmatic execution and graceful shutdown:
# runner.start(100, 20)
# gevent.spawn(stats_printer(env.stats))
# gevent.spawn(stats_history(env.stats))
# gevent.sleep(60) # Run for 60 seconds
# runner.quit()
# ----------------------------------
This approach gives you fine-grained control, allowing you to set the user_classes, host, target_user_count, spawn_rate, and more, directly in your Python code before starting the test. It’s the most flexible but also the most verbose method.
You might next wonder how to integrate Locust’s reporting into external systems.