Configuration

Command Line Options

Locust is configured mainly through command line arguments.

$ locust --help
Usage: locust [OPTIONS] [UserClass ...]

Common options:
  -h, --help            show this help message and exit
  -f LOCUSTFILE, --locustfile LOCUSTFILE
                        Python module to import, e.g. '../other_test.py'.
                        Either a .py file, multiple comma-separated .py files
                        or a package directory. Defaults to 'locustfile'.
  --config CONFIG       Config file path
  -H HOST, --host HOST  Host to load test in the following format:
                        http://10.21.32.33
  -u NUM_USERS, --users NUM_USERS
                        Peak number of concurrent Locust users. Primarily used
                        together with --headless or --autostart. Can be
                        changed during a test by keyboard inputs w, W (spawn
                        1, 10 users) and s, S (stop 1, 10 users)
  -r SPAWN_RATE, --spawn-rate SPAWN_RATE
                        Rate to spawn users at (users per second). Primarily
                        used together with --headless or --autostart
  -t RUN_TIME, --run-time RUN_TIME
                        Stop after the specified amount of time, e.g. (300s,
                        20m, 3h, 1h30m, etc.). Only used together with
                        --headless or --autostart. Defaults to run forever.
  -l, --list            Show list of possible User classes and exit

Web UI options:
  --web-host WEB_HOST   Host to bind the web interface to. Defaults to '*'
                        (all interfaces)
  --web-port WEB_PORT, -P WEB_PORT
                        Port on which to run web host
  --headless            Disable the web interface, and start the test
                        immediately. Use -u and -t to control user count and
                        run time
  --autostart           Starts the test immediately (without disabling the web
                        UI). Use -u and -t to control user count and run time
  --autoquit AUTOQUIT   Quits Locust entirely, X seconds after the run is
                        finished. Only used together with --autostart. The
                        default is to keep Locust running until you shut it
                        down using CTRL+C
  --web-auth WEB_AUTH   Turn on Basic Auth for the web interface. Should be
                        supplied in the following format: username:password
  --tls-cert TLS_CERT   Optional path to TLS certificate to use to serve over
                        HTTPS
  --tls-key TLS_KEY     Optional path to TLS private key to use to serve over
                        HTTPS
  --class-picker        Enable select boxes in the web interface to choose
                        from all available User classes and Shape classes

Master options:
  Options for running a Locust Master node when running Locust distributed. A Master node need Worker nodes that connect to it before it can run load tests.

  --master              Set locust to run in distributed mode with this
                        process as master
  --master-bind-host MASTER_BIND_HOST
                        Interfaces (hostname, ip) that locust master should
                        bind to. Only used when running with --master.
                        Defaults to * (all available interfaces).
  --master-bind-port MASTER_BIND_PORT
                        Port that locust master should bind to. Only used when
                        running with --master. Defaults to 5557.
  --expect-workers EXPECT_WORKERS
                        How many workers master should expect to connect
                        before starting the test (only when
                        --headless/autostart is used).
  --expect-workers-max-wait EXPECT_WORKERS_MAX_WAIT
                        How long should the master wait for workers to connect
                        before giving up. Defaults to wait forever

Worker options:
  Options for running a Locust Worker node when running Locust distributed.
  Only the LOCUSTFILE (-f option) needs to be specified when starting a Worker, since other options such as -u, -r, -t are specified on the Master node.

  --worker              Set locust to run in distributed mode with this
                        process as worker
  --master-host MASTER_NODE_HOST
                        Host or IP address of locust master for distributed
                        load testing. Only used when running with --worker.
                        Defaults to 127.0.0.1.
  --master-port MASTER_NODE_PORT
                        The port to connect to that is used by the locust
                        master for distributed load testing. Only used when
                        running with --worker. Defaults to 5557.

Tag options:
  Locust tasks can be tagged using the @tag decorator. These options let specify which tasks to include or exclude during a test.

  -T [TAG [TAG ...]], --tags [TAG [TAG ...]]
                        List of tags to include in the test, so only tasks
                        with any matching tags will be executed
  -E [TAG [TAG ...]], --exclude-tags [TAG [TAG ...]]
                        List of tags to exclude from the test, so only tasks
                        with no matching tags will be executed

Request statistics options:
  --csv CSV_PREFIX      Store current request stats to files in CSV format.
                        Setting this option will generate three files:
                        [CSV_PREFIX]_stats.csv, [CSV_PREFIX]_stats_history.csv
                        and [CSV_PREFIX]_failures.csv
  --csv-full-history    Store each stats entry in CSV format to
                        _stats_history.csv file. You must also specify the '--
                        csv' argument to enable this.
  --print-stats         Print stats in the console
  --only-summary        Only print the summary stats
  --reset-stats         Reset statistics once spawning has been completed.
                        Should be set on both master and workers when running
                        in distributed mode
  --html HTML_FILE      Store HTML report to file path specified

Logging options:
  --skip-log-setup      Disable Locust's logging setup. Instead, the
                        configuration is provided by the Locust test or Python
                        defaults.
  --loglevel LOGLEVEL, -L LOGLEVEL
                        Choose between DEBUG/INFO/WARNING/ERROR/CRITICAL.
                        Default is INFO.
  --logfile LOGFILE     Path to log file. If not set, log will go to stderr

Other options:
  --show-task-ratio     Print table of the User classes' task execution ratio.
                        Use this with non-zero --user option if some classes
                        define non-zero fixed_count attribute.
  --show-task-ratio-json
                        Print json data of the User classes' task execution
                        ratio. Use this with non-zero --user option if some
                        classes define non-zero fixed_count attribute.
  --version, -V         Show program's version number and exit
  --exit-code-on-error EXIT_CODE_ON_ERROR
                        Sets the process exit code to use when a test result
                        contain any failure or error
  -s STOP_TIMEOUT, --stop-timeout STOP_TIMEOUT
                        Number of seconds to wait for a simulated user to
                        complete any executing task before exiting. Default is
                        to terminate immediately. This parameter only needs to
                        be specified for the master process when running
                        Locust distributed.
  --equal-weights       Use equally distributed task weights, overriding the
                        weights specified in the locustfile.
  --enable-rebalancing  Allow to automatically rebalance users if new workers
                        are added or removed during a test run.

User classes:
  UserClass             Optionally specify which User classes that should be
                        used (available User classes can be listed with -l or
                        --list)

Environment Variables

Options can also be set through through environment variables. They are typically the same as the command line argument but capitalized and prefixed with LOCUST_:

On Linux/macOS:

$ LOCUST_LOCUSTFILE=custom_locustfile.py locust

On Windows:

> set LOCUST_LOCUSTFILE=custom_locustfile.py
> locust

Configuration File

Options can also be set in a configuration file in the config file format.

Locust will look for ~/.locust.conf and ./locust.conf by default, and you can specify an additional file using the --config flag.

Example:

# master.conf in current directory
locustfile = locust_files/my_locust_file.py
headless = true
master = true
expect-workers = 5
host = http://target-system
users = 100
spawn-rate = 10
run-time = 10m
$ locust --config=master.conf

Note

Configuration values are read (overridden) in the following order:

~/locust.conf -> ./locust.conf -> (file specified using --conf) -> env vars -> cmd args

All available configuration options

Here’s a table of all the available configuration options, and their corresponding Environment and config file keys:

Command line

Environment

Config file

Description

-f, --locustfile

LOCUST_LOCUSTFILE

locustfile

Python module to import, e.g. ‘../other_test.py’. Either a .py file, multiple comma-separated .py files or a package directory. Defaults to ‘locustfile’.

-H, --host

LOCUST_HOST

host

Host to load test in the following format: http://10.21.32.33

-u, --users

LOCUST_USERS

users

Peak number of concurrent Locust users. Primarily used together with –headless or –autostart. Can be changed during a test by keyboard inputs w, W (spawn 1, 10 users) and s, S (stop 1, 10 users)

-r, --spawn-rate

LOCUST_SPAWN_RATE

spawn-rate

Rate to spawn users at (users per second). Primarily used together with –headless or –autostart

-t, --run-time

LOCUST_RUN_TIME

run-time

Stop after the specified amount of time, e.g. (300s, 20m, 3h, 1h30m, etc.). Only used together with –headless or –autostart. Defaults to run forever.

--web-host

LOCUST_WEB_HOST

web-host

Host to bind the web interface to. Defaults to ‘*’ (all interfaces)

--web-port, -P

LOCUST_WEB_PORT

web-port

Port on which to run web host

--headless

LOCUST_HEADLESS

headless

Disable the web interface, and start the test immediately. Use -u and -t to control user count and run time

--autostart

LOCUST_AUTOSTART

autostart

Starts the test immediately (without disabling the web UI). Use -u and -t to control user count and run time

--autoquit

LOCUST_AUTOQUIT

autoquit

Quits Locust entirely, X seconds after the run is finished. Only used together with –autostart. The default is to keep Locust running until you shut it down using CTRL+C

--web-auth

LOCUST_WEB_AUTH

web-auth

Turn on Basic Auth for the web interface. Should be supplied in the following format: username:password

--tls-cert

LOCUST_TLS_CERT

tls-cert

Optional path to TLS certificate to use to serve over HTTPS

--tls-key

LOCUST_TLS_KEY

tls-key

Optional path to TLS private key to use to serve over HTTPS

--class-picker

LOCUST_USERCLASS_PICKER

class-picker

Enable select boxes in the web interface to choose from all available User classes and Shape classes

--master

LOCUST_MODE_MASTER

master

Set locust to run in distributed mode with this process as master

--master-bind-host

LOCUST_MASTER_BIND_HOST

master-bind-host

Interfaces (hostname, ip) that locust master should bind to. Only used when running with –master. Defaults to * (all available interfaces).

--master-bind-port

LOCUST_MASTER_BIND_PORT

master-bind-port

Port that locust master should bind to. Only used when running with –master. Defaults to 5557.

--expect-workers

LOCUST_EXPECT_WORKERS

expect-workers

How many workers master should expect to connect before starting the test (only when –headless/autostart is used).

--expect-workers-max-wait

LOCUST_EXPECT_WORKERS_MAX_WAIT

expect-workers-max-wait

How long should the master wait for workers to connect before giving up. Defaults to wait forever

--worker

LOCUST_MODE_WORKER

worker

Set locust to run in distributed mode with this process as worker

--master-host

LOCUST_MASTER_NODE_HOST

master-host

Host or IP address of locust master for distributed load testing. Only used when running with –worker. Defaults to 127.0.0.1.

--master-port

LOCUST_MASTER_NODE_PORT

master-port

The port to connect to that is used by the locust master for distributed load testing. Only used when running with –worker. Defaults to 5557.

-T, --tags

LOCUST_TAGS

tags

List of tags to include in the test, so only tasks with any matching tags will be executed

-E, --exclude-tags

LOCUST_EXCLUDE_TAGS

exclude-tags

List of tags to exclude from the test, so only tasks with no matching tags will be executed

--csv

LOCUST_CSV

csv

Store current request stats to files in CSV format. Setting this option will generate three files: [CSV_PREFIX]_stats.csv, [CSV_PREFIX]_stats_history.csv and [CSV_PREFIX]_failures.csv

--csv-full-history

LOCUST_CSV_FULL_HISTORY

csv-full-history

Store each stats entry in CSV format to _stats_history.csv file. You must also specify the ‘–csv’ argument to enable this.

--print-stats

LOCUST_PRINT_STATS

print-stats

Print stats in the console

--only-summary

LOCUST_ONLY_SUMMARY

only-summary

Only print the summary stats

--reset-stats

LOCUST_RESET_STATS

reset-stats

Reset statistics once spawning has been completed. Should be set on both master and workers when running in distributed mode

--html

LOCUST_HTML

html

Store HTML report to file path specified

--skip-log-setup

LOCUST_SKIP_LOG_SETUP

skip-log-setup

Disable Locust’s logging setup. Instead, the configuration is provided by the Locust test or Python defaults.

--loglevel, -L

LOCUST_LOGLEVEL

loglevel

Choose between DEBUG/INFO/WARNING/ERROR/CRITICAL. Default is INFO.

--logfile

LOCUST_LOGFILE

logfile

Path to log file. If not set, log will go to stderr

--exit-code-on-error

LOCUST_EXIT_CODE_ON_ERROR

exit-code-on-error

Sets the process exit code to use when a test result contain any failure or error

-s, --stop-timeout

LOCUST_STOP_TIMEOUT

stop-timeout

Number of seconds to wait for a simulated user to complete any executing task before exiting. Default is to terminate immediately. This parameter only needs to be specified for the master process when running Locust distributed.

Running without the web UI

See Running without the web UI

Using multiple Locustfiles at once

The -f/--locustfile option accepts a single directory of locustfiles as an option. Locust will recursively search the directory for *.py files, ignoring files named locust.py or those that start with “_”.

Example:

With the following file structure:

├── locustfiles/
│   ├── locustfile1.py
│   ├── locustfile2.py
│   └── more_files/
│       ├── locustfile3.py
│       ├── locust.py
│       ├── _ignoreme.py
$ locust -f locustfiles

Locust will use locustfile1.py, locustfile2.py & more_files/locustfile3.py

Additionally, -f/--locustfile accepts multiple, comma-separated locustfiles.

Example:

$ locust -f locustfiles/locustfile1.py,locustfiles/locustfile2.py,locustfiles/more_files/locustfile3.py

Locust will use locustfile1.py, locustfile2.py & more_files/locustfile3.py

Running Locust with User class UI picker

You can select which Shape class and which User classes to run in the WebUI when running locust with the --class-picker flag. No selection uses all of the available User classes.

Example:

With the following file structure:

├── src/
│   ├── some_file.py
├── locustfiles/
│   ├── locustfile1.py
│   ├── locustfile2.py
│   └── more_files/
│       ├── locustfile3.py
│       ├── locust.py
│       ├── _ignoreme.py
│   └── shape_classes/
│       ├── DoubleWaveShape.py
│       ├── StagesShape.py
$ locust -f locustfiles --class-picker

The Web UI will display:

_images/userclass_picker_example.png

Custom arguments

See Custom arguments

Customization of statistics settings

Default configuration for Locust statistics is set in constants of stats.py file. It can be tuned to specific requirements by overriding these values. To do this, import locust.stats module and override required settings:

import locust.stats
locust.stats.CONSOLE_STATS_INTERVAL_SEC = 15

It can be done directly in Locust file or extracted to separate file for common usage by all Locust files.

The list of statistics parameters that can be modified is:

Parameter name

Purpose

STATS_NAME_WIDTH

Width of column for request name in console output

STATS_TYPE_WIDTH

Width of column for request type in console output

CSV_STATS_INTERVAL_SEC

Interval for how frequently the CSV file is written if this option is configured

CONSOLE_STATS_INTERVAL_SEC

Interval for how frequently results are written to console

CURRENT_RESPONSE_TIME_PERCENTILE_WINDOW

Window size/resolution - in seconds - when calculating the current response time percentile

PERCENTILES_TO_REPORT

The list of response time percentiles to be calculated & reported