TopGit
GitHub Repo Review

Locust load testing: write tests in Python

locustio/locust
LTopGit review image for locustio/locust
Review by Topgit.dev for locustio/locust, with GitHub repository stats and README context.
Quick verdict

Locust turns load testing into ordinary Python code instead of a GUI or an XML test plan, and that's the whole pitch. Its gevent-based greenlets let a single process simulate many concurrent users without one OS thread per user, which is why teams outgrowing JMeter's XML files land here. It won't out-throughput every tool on raw requests per second, but for scripting realistic multi-step user flows it wins.

Stars
★ 28.3k
Forks
⑂ 3.3k
Contributors
👥 395
Language
Python
License
MIT
Topic
Backend
Updated
Nov 2026
Homepage
GitHub

Why load testing matters

Most load testing tools force you to describe user behavior in a GUI, a proprietary DSL, or XML test plans that don't version well and are painful to branch, review, or generate programmatically. A checkout flow with conditional logic, retries, or randomized item IDs turns into either a wall of copy-pasted GUI steps or a script cobbled together in a tool-specific scripting dialect. Locust exists to answer that user-behavior-as-code problem directly: plain Python, run with a normal interpreter.

What is Locust?

Locust is an open source load testing tool that lets you write test scenarios as plain Python classes instead of a GUI or DSL. Each simulated user runs inside its own gevent greenlet, so a single Python process can drive many concurrent users with lower overhead than a thread-per-user model. You can run it from the command line or through its web UI, which shows throughput, response times, and errors as the test runs.

Key features

  • ✓Test scenarios are Python classes (HttpUser subclasses) with @task-decorated methods, so branching, loops, and randomized data use normal Python instead of a DSL.
  • ✓Each virtual user runs in its own gevent greenlet, letting one process handle many concurrent users without a thread per user.
  • ✓A web UI shows live throughput, response times, and error counts, and lets you change the user count mid-run.
  • ✓Can run headless, with no UI, from the CLI, which the README calls out as suited to CI/CD pipelines.
  • ✓Distributes across multiple machines for larger tests, per the README's distributed/scalable description.
  • ✓Not limited to HTTP — the README says you can write a client for any protocol, or reuse ones the community has already built.
  • ✓Pluggable architecture: the README points to real examples like piping results into TimescaleDB and visualizing them in Grafana, or using a custom load shape.
How this repository's GitHub stars have grown over time. Source: star-history.com.View the star history ↗

What to use Locust for

  • •Simulating realistic multi-step user journeys against a web app or API, like login-then-browse-then-checkout, coded as ordered @task methods.
  • •Stress-testing to find the concurrency point where response times or error rates degrade.
  • •Running load tests as a CI/CD gate in headless mode before a deploy ships.
  • •Testing non-HTTP systems by writing a custom client, per the README's guidance for protocols beyond HTTP.
  • •Distributing tests across multiple machines when a single process can't generate enough load.

Installing Locust

The README doesn't spell out install commands itself — it points to the official documentation's installation page instead. Based on what's given here, the exact install command isn't clearly documented; check the linked docs for current instructions rather than assuming a specific command from this page.

Writing your first load test

A first test is a Python class that subclasses HttpUser, sets a wait_time between requests, and defines one or more @task methods that call self.client.get() or self.client.post() against the target host. Task weights control how often each one runs — the README's example weights one task 3x over another using @task(3). From there you run the file, either through the web UI to watch live metrics and adjust user count on the fly, or headless from the command line, which the README frames as fitting CI/CD.

Pros

  • ✓Test logic is ordinary Python, so it lives in version control, gets code review, and reuses your existing IDE and libraries instead of a vendor-specific format.
  • ✓The web UI lets you watch throughput and error rates live and adjust concurrent users mid-test without restarting.
  • ✓Greenlet-based concurrency keeps per-user overhead low, per the README, without needing a thread per simulated user.
  • ✓Headless mode drops cleanly into CI/CD pipelines since there's no UI dependency to script around.
  • ✓The architecture is pluggable — the README links to real examples like piping results into TimescaleDB and Grafana.

Limitations

  • △Writing tests in Python means you need to actually know Python — there's no GUI recorder or XML plan for non-programmers to fall back on.
  • △The README doesn't state raw requests-per-second numbers, and it explicitly admits other tools may out-throughput Locust on a single machine for pure request volume.
  • △Installation steps aren't in the README itself; you're routed to external docs, so the initial on-ramp depends on documentation you have to leave the repo to read.
View on GitHub ↗Homepage ↗

Locust vs JMeter, k6, and Gatling

JMeter — GUI/XML-based load testing tool; broader protocol support out of the box but tests aren't plain code.k6 — JavaScript-scripted load testing tool with a similar code-first approach but a different language and runtime.Gatling — Scala-based load testing tool with a code-first DSL, positioned similarly to Locust but on the JVM.wrk — a lightweight HTTP benchmarking tool for raw throughput numbers rather than scripted user behavior. ↗

Frequently asked questions

Is Locust free and open source?

Locust is free and open source software, released under the MIT license. That means you can use, modify, and redistribute it without paying for a license, and the source lives on GitHub, so teams can audit or change the code themselves instead of depending on a closed vendor tool.

Can Locust test systems other than HTTP?

Locust can test protocols beyond HTTP — the project's README says that even though it primarily targets web sites and services, you can write a custom client for almost any protocol you want to test, and links to community-built clients others have already written for different systems.

How does Locust achieve high concurrency with low overhead?

Locust achieves high concurrency by running each simulated user inside its own gevent greenlet rather than an operating system thread. Greenlets are lightweight coroutines, so a single Python process can juggle many concurrent users with far less memory and scheduling overhead than a thread-per-user design needs.

Can Locust tests run in CI/CD pipelines?

Locust tests can run in CI/CD pipelines because the tool supports a headless mode with no web UI required. You launch it straight from the command line as part of a pipeline step, which the project describes as making it easy to fold performance testing into automated CI/CD workflows.

Does Locust have a web interface?

Locust ships with a web-based UI that shows a running test's progress in real time, including throughput, response times, and errors. You can also change the number of simulated users while the test is still running, and the UI is optional — you can skip it entirely and run headless instead.

How does Locust scale across multiple machines?

Locust scales across multiple machines through a distributed mode built for running load tests spread over more than one host. That's how it supports simulating very large numbers of concurrent users — a single machine's CPU stops being the ceiling once the load is spread across a cluster of worker machines.

Who should try it — and who should skip

Teams that already write their test setup, fixtures, and business logic in Python get the most out of Locust — the whole value proposition disappears if you'd rather never see a line of code. It also suits anyone whose test scenarios have real branching, conditional steps, retries, or randomized inputs, that a GUI recorder handles awkwardly. Skip it if you need a no-code tool for non-developers to build tests, or if raw single-machine requests-per-second is the only number that matters — the README itself concedes other tools can push more requests per second on the same hardware.

Related repositories

Source & attribution

Based on the locustio/locust GitHub repository (github.com/locustio/locust), including its README and repo metadata.

GitHub data · last synced Aug 15, 2026Reviewed by Henry
← Back to TopGit

Want a second opinion on locust?

Ask an AI that can read this page — one click and you get its take on locust.

GitHub