# locustio/locust architecture

> Architecture diagram of the GitHub repository locustio/locust, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/locustio/locust
- Repository: https://github.com/locustio/locust

## Overview

Locust turns Python user scenarios into concurrent load, then reports request throughput, latency, and failures locally or across workers. The main route is scenario loading and configuration, user/task execution, protocol requests, aggregation, and live UI or exported results. Custom load shapes and non-HTTP clients extend that route. Source excerpts establish the core execution and request path; several UI, reporting, and integration links rely on README statements because their implementation was not sampled.

Main entry points: [`locust/runners.py`](https://github.com/locustio/locust/blob/master/locust/runners.py) (Runners), [`locust/user/users.py`](https://github.com/locustio/locust/blob/master/locust/user/users.py) (User runtime), [`locust/env.py`](https://github.com/locustio/locust/blob/master/locust/env.py) (Test environment), [`locust/stats.py`](https://github.com/locustio/locust/blob/master/locust/stats.py) (Statistics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Scenario authoring"]
  node_scenario["Python scenarios<br/>[load_locustfile.py]"]
  node_cli["CLI options<br/>[argument_parser.py]"]
end

subgraph group_execution["Load execution"]
  node_tasks["Tasks and users<br/>[task.py]"]
  node_user_runtime["User runtime<br/>[users.py]"]
  node_http_client["HTTP client<br/>[clients.py]"]
end

subgraph group_coordination["Runtime coordination"]
  node_environment["Test environment<br/>[env.py]"]
  node_runner["Runners<br/>[runners.py]"]
  node_dispatch["User dispatcher<br/>[dispatch.py]"]
  node_load_shape["Load shapes<br/>[shape.py]"]
  node_rpc["Worker RPC<br/>[zmqrpc.py]"]
  node_events["Request events<br/>[event.py]"]
end

subgraph group_reporting["Reporting"]
  node_stats[("Statistics<br/>[stats.py]")]
  node_web_backend["Web backend<br/>[web.py]"]
  node_web_ui["Web interface<br/>[App.tsx]"]
  node_html_report["HTML report<br/>[html.py]"]
end

subgraph group_extensions["Protocol extensions"]
  node_fast_client["Fast HTTP<br/>[fasthttp.py]"]
  node_other_clients["Other protocols"]
end

node_operator(("Test operator"))
node_target[("System under test")]

node_operator -->|"configures run"| node_cli
node_cli -->|"selects file"| node_scenario
node_scenario -->|"defines classes"| node_environment
node_cli -->|"configures"| node_environment
node_environment -->|"creates"| node_runner
node_runner -->|"spawns users"| node_user_runtime
node_user_runtime -->|"runs tasks"| node_tasks
node_user_runtime -->|"creates client"| node_http_client
node_tasks -->|"defines behavior"| node_user_runtime
node_http_client -->|"sends requests"| node_target
node_user_runtime -->|"uses protocol client"| node_fast_client
node_fast_client -->|"sends requests"| node_target
node_other_clients -.->|"tests protocols"| node_target
node_http_client -->|"fires request events"| node_events
node_events -->|"records requests"| node_stats
node_runner -->|"distributes users"| node_dispatch
node_environment -->|"attaches shape"| node_load_shape
node_load_shape -->|"controls load"| node_runner
node_runner -->|"coordinates workers"| node_rpc
node_runner -->|"aggregates reports"| node_stats
node_operator -->|"monitors run"| node_web_ui
node_web_ui -->|"requests live data"| node_web_backend
node_web_backend -->|"controls test"| node_environment
node_web_backend -.->|"serves statistics"| node_stats
node_stats -->|"supplies results"| node_html_report
node_runner -->|"writes report"| node_html_report

click node_scenario "https://github.com/locustio/locust/blob/master/locust/util/load_locustfile.py"
click node_cli "https://github.com/locustio/locust/blob/master/locust/argument_parser.py"
click node_tasks "https://github.com/locustio/locust/blob/master/locust/user/task.py"
click node_user_runtime "https://github.com/locustio/locust/blob/master/locust/user/users.py"
click node_http_client "https://github.com/locustio/locust/blob/master/locust/clients.py"
click node_fast_client "https://github.com/locustio/locust/blob/master/locust/contrib/fasthttp.py"
click node_other_clients "https://github.com/locustio/locust/tree/master/locust/contrib"
click node_environment "https://github.com/locustio/locust/blob/master/locust/env.py"
click node_runner "https://github.com/locustio/locust/blob/master/locust/runners.py"
click node_dispatch "https://github.com/locustio/locust/blob/master/locust/dispatch.py"
click node_load_shape "https://github.com/locustio/locust/blob/master/locust/shape.py"
click node_rpc "https://github.com/locustio/locust/blob/master/locust/rpc/zmqrpc.py"
click node_events "https://github.com/locustio/locust/blob/master/locust/event.py"
click node_stats "https://github.com/locustio/locust/blob/master/locust/stats.py"
click node_web_backend "https://github.com/locustio/locust/blob/master/locust/web.py"
click node_web_ui "https://github.com/locustio/locust/blob/master/locust/webui/src/App.tsx"
click node_html_report "https://github.com/locustio/locust/blob/master/locust/html.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_scenario,node_cli toneBlue
class node_tasks,node_user_runtime,node_http_client,node_target toneAmber
class node_environment,node_runner,node_dispatch,node_load_shape,node_rpc,node_events toneMint
class node_stats,node_web_backend,node_web_ui,node_html_report toneRose
class node_fast_client,node_other_clients,node_operator toneIndigo
```

## Components

### Scenario authoring

- [Python scenarios](https://github.com/locustio/locust/blob/master/locust/util/load_locustfile.py): `locust/util/load_locustfile.py`
- [CLI options](https://github.com/locustio/locust/blob/master/locust/argument_parser.py): `locust/argument_parser.py`

### Load execution

- [Tasks and users](https://github.com/locustio/locust/blob/master/locust/user/task.py): `locust/user/task.py`
- [User runtime](https://github.com/locustio/locust/blob/master/locust/user/users.py): `locust/user/users.py`
- [HTTP client](https://github.com/locustio/locust/blob/master/locust/clients.py): `locust/clients.py`

### Runtime coordination

- [Test environment](https://github.com/locustio/locust/blob/master/locust/env.py): `locust/env.py`
- [Runners](https://github.com/locustio/locust/blob/master/locust/runners.py): `locust/runners.py`
- [User dispatcher](https://github.com/locustio/locust/blob/master/locust/dispatch.py): `locust/dispatch.py`
- [Load shapes](https://github.com/locustio/locust/blob/master/locust/shape.py): `locust/shape.py`
- [Worker RPC](https://github.com/locustio/locust/blob/master/locust/rpc/zmqrpc.py): `locust/rpc/zmqrpc.py`
- [Request events](https://github.com/locustio/locust/blob/master/locust/event.py): `locust/event.py`

### Reporting

- [Statistics](https://github.com/locustio/locust/blob/master/locust/stats.py): `locust/stats.py`
- [Web backend](https://github.com/locustio/locust/blob/master/locust/web.py): `locust/web.py`
- [Web interface](https://github.com/locustio/locust/blob/master/locust/webui/src/App.tsx): `locust/webui/src/App.tsx`
- [HTML report](https://github.com/locustio/locust/blob/master/locust/html.py): `locust/html.py`

### Protocol extensions

- [Fast HTTP](https://github.com/locustio/locust/blob/master/locust/contrib/fasthttp.py): `locust/contrib/fasthttp.py`
- [Other protocols](https://github.com/locustio/locust/tree/master/locust/contrib): `locust/contrib`

### Other components

- **Test operator**
- **System under test**

## Connections

- Test operator → CLI options: configures run
- CLI options → Python scenarios: selects file (evidence: `locust/main.py`)
- Python scenarios → Test environment: defines classes (evidence: `locust/main.py`)
- CLI options → Test environment: configures (evidence: `locust/main.py`)
- Test environment → Runners: creates (evidence: `locust/env.py`)
- Runners → User runtime: spawns users (evidence: `locust/runners.py`)
- User runtime → Tasks and users: runs tasks (evidence: `locust/user/users.py`)
- User runtime → HTTP client: creates client (evidence: `locust/user/users.py`)
- Tasks and users → User runtime: defines behavior (evidence: `locust/user/task.py`)
- HTTP client → System under test: sends requests
- User runtime → Fast HTTP: uses protocol client (evidence: `locust/contrib/fasthttp.py`)
- Fast HTTP → System under test: sends requests
- Other protocols → System under test: tests protocols
- HTTP client → Request events: fires request events (evidence: `locust/clients.py`)
- Request events → Statistics: records requests (evidence: `locust/stats.py`)
- Runners → User dispatcher: distributes users (evidence: `locust/runners.py`)
- Test environment → Load shapes: attaches shape (evidence: `locust/env.py`)
- Load shapes → Runners: controls load (evidence: `locust/shape.py`)
- Runners → Worker RPC: coordinates workers (evidence: `locust/runners.py`)
- Runners → Statistics: aggregates reports (evidence: `locust/stats.py`)
- Test operator → Web interface: monitors run
- Web interface → Web backend: requests live data
- Web backend → Test environment: controls test (evidence: `locust/env.py`)
- Web backend → Statistics: serves statistics
- Statistics → HTML report: supplies results (evidence: `locust/html.py`)
- Runners → HTML report: writes report (evidence: `locust/html.py`)
