How to Run Locust Headless in CI

Locust in headless mode runs a fixed duration and can return a non-zero exit code when failures occur, giving CI a clean pass/fail signal.

Run locust --headless with a user count (-u), spawn rate (-r), and --run-time. Add --exit-code-on-error 1 so any request failure fails the CI step.

Steps

Install Locust with pip install locust.
Run headless with -u, -r, --run-time, and a --host.
Add --exit-code-on-error 1 to gate on failures.

Terminal

pip install locust
locust -f locustfile.py --headless \
  -u 100 -r 10 --run-time 2m \
  --host https://staging.example.com \
  --exit-code-on-error 1

Workflow

.github/workflows/ci.yml

jobs:
  locust:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install locust
      - run: locust -f locustfile.py --headless -u 100 -r 10 --run-time 2m --host https://staging.example.com --exit-code-on-error 1

Gotchas

Without --exit-code-on-error, Locust exits 0 even when every request 500s.
Set --run-time or the headless run continues until the process is killed.