Guide · Open source

How to use Locust: install, write a load test and run it

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Locust is a free, MIT-licensed load testing tool for HTTP and other protocols. You describe user behavior in regular Python code, then run the test from the command line or a web interface. This guide covers installing Locust, writing a basic test, running it, and deciding whether it suits your team.

Locustlocustio/locust · ★ 28.3k · MIT Install options & downloads

Quick start

1Check Python is installed. Locust requires Python. Confirm you have a working Python environment before installing.
2Install Locust. Run pip install locust to install the package from PyPI.
3Write a user class. Create a Python file with a class that inherits from HttpUser and define tasks using the @task decorator.
4Set wait times and setup. Use wait_time to pause users between tasks and on_start for per-user setup such as logging in.
5Start the test. Run Locust from the command line to open the web UI, or run it without the UI for automated pipelines.
6Watch and export results. Monitor throughput, response times and errors in real time, and export the data for later analysis.

What Locust is and who it suits

Load testing means simulating many users at once to see how a web service or other system behaves under pressure. Locust does this with tests written as ordinary Python code, so they can be kept in version control and edited in a normal IDE.

The README describes Locust as working primarily with HTTP, with other protocols supported through a custom client. It is a good fit for backend or QA engineers, Python teams that want to reuse existing libraries, and teams running tests in CI/CD without a GUI. It is not a no-code tool.

Install Locust with pip

Locust's prerequisite is Python. The README's install method is the PyPI package, installed with pip. The documentation linked from the README has full installation details.

pip install locust

Write your first test file

A test is a Python class that inherits from a user class such as HttpUser. Each user runs its tasks in its own lightweight greenlet, so you write blocking-style code instead of callbacks. The @task decorator marks methods that simulated users perform, and the optional number in @task(3) sets how often a task is picked relative to others. wait_time controls the pause between tasks, and on_start runs once when a user starts.

The example below comes from the README's quickstart. It logs in once per user, then runs two tasks, with view_item weighted three times higher than hello_world. The name argument groups many item requests under one label in the statistics.

wait_time = between(1, 2) pauses each user between one and two seconds
on_start performs setup such as logging in
@task(3) makes that task three times as likely as an untagged task
name="/item" groups all item URLs under one entry

from locust import HttpUser, task, between


class QuickstartUser(HttpUser):
    wait_time = between(1, 2)

    def on_start(self):
        self.client.post("/login", json={"username": "foo", "password": "bar"})

    @task
    def hello_world(self):
        self.client.get("/hello")
        self.client.get("/world")

    @task(3)
    def view_item(self):
        for item_id in range(10):
            self.client.get(f"/item?id={item_id}", name="/item")

Run the test from the command line or web UI

Locust tests can be run from the command line or through the web-based UI. The UI shows the progress of the test in real time, and you can change the load while the test runs. Throughput, response times and errors can be viewed live and exported for later analysis.

For CI/CD pipelines, Locust can run without the UI, which makes it straightforward to automate. The README notes that Locust is event-based using gevent, so a single process can handle many thousands of concurrent users, and tests can be distributed over multiple machines.

Web UI: live charts for throughput, response times and errors
Headless mode: suitable for automated CI/CD runs
Distributed runs: spread load across several machines

Extend Locust with normal Python

Because tests are plain Python, you can import ordinary libraries into them. The README lists examples of what you can do, such as sending real-time reporting data to TimescaleDB and visualizing it in Grafana, wrapping calls to handle the quirks of a REST API, or using a custom load shape.

If you need to test a system that is not HTTP, the README says you can write a client for it. Community-made extensions are listed in the project's wiki and the locust-plugins repository.

Use Locust with Azure or the VS Code extension

The README describes a Microsoft VS Code extension that uses Copilot to help create and run Locust tests. It also describes Azure Load Testing, a managed service for running and scaling Locust tests without hosting your own infrastructure. The README points to Locust Cloud at locust.cloud as a separate option; it does not describe a built-in hosted service in the open-source project itself.

VS Code extension: created by Microsoft, with Copilot assistance
Azure Load Testing: managed service that can combine results with Azure resource metrics
Locust Cloud: linked from the README homepage

What people use it for

Simulating many concurrent users logging in and browsing an HTTP web service
Keeping load test scenarios in a Git repository alongside application code
Running headless load tests as a step in a CI/CD pipeline
Reusing an existing Python client library inside a load test
Spreading a high-concurrency test across several machines

Frequently asked questions

Is Locust free to use?

Yes. The README states that Locust is open source under the MIT license. You can use it without paying for the tool itself.

How do I install Locust?

The README gives the install command pip install locust, which installs the package from PyPI. Python is the prerequisite.

Does Locust require coding knowledge?

Yes. Tests are written in Python, so Locust is not a no-code tool. Teams that want no-code testing should consider other options.

Can Locust test things other than websites?

The README says Locust works primarily with HTTP but can test almost any system or protocol. You need to write a client for the protocol you want to test, or use one from the community.

Does Locust run in CI/CD pipelines?

Yes. The README says Locust can run without the web UI, which makes it easy to use for CI/CD testing.

How does Locust compare to k6, Gatling or JMeter?

Locust's distinguishing feature is writing tests in plain Python. k6, Gatling, Apache JMeter and Artillery are comparable projects, and the right choice depends on whether your team prefers Python, JavaScript, Scala or a GUI-based tool.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Locust suits backend and QA engineers, and Python teams, who want load tests as version-controlled code that runs headless in CI or from a live web UI. Skip it if you want a no-code tool or need to test non-HTTP systems and are unwilling to write a custom client.

Install options & downloads