Write test scenarios in pure Python

No need for clunky UIs or bloated XML, just plain code

Distributed & Scalable

Locust supports running load tests distributed over multiple machines, and can therefore be used to simulate millions of simultaneous users

Web based UI

Even though all tests are Python code, Locust has a neat web interface that shows relevant test details in real-time during test runs


Locust has been used to simulate millions of simultaneous users, swarming a single system

Screenshot of Locust UI


$ pip install locustioMore info »

Simple to use

  1. Simple example
  2. Example with HTML parsing
# locustfile.py

from locust import HttpLocust, TaskSet, task

class WebsiteTasks(TaskSet):
    def on_start(self):
        self.client.post("/login", {
            "username": "test_user",
            "password": ""
    def index(self):
    def about(self):

class WebsiteUser(HttpLocust):
    task_set = WebsiteTasks
    min_wait = 5000
    max_wait = 15000
$ locust -f locustfile.py -H http://site.comRead more in documentation »
# This locust test script example will simulate a user 
# browsing the Locust documentation on http://docs.locust.io

import random
from locust import HttpLocust, TaskSet, task
from pyquery import PyQuery

class BrowseDocumentation(TaskSet):
    def on_start(self):
        # assume all users arrive at the index page
        self.urls_on_current_page = self.toc_urls
    def index_page(self):
        r = self.client.get("/")
        pq = PyQuery(r.content)
        link_elements = pq(".toctree-wrapper a.internal")
        self.toc_urls = [
            l.attrib["href"] for l in link_elements
    def load_page(self, url=None):
        url = random.choice(self.toc_urls)
        r = self.client.get(url)
        pq = PyQuery(r.content)
        link_elements = pq("a.internal")
        self.urls_on_current_page = [
            l.attrib["href"] for l in link_elements
    def load_sub_page(self):
        url = random.choice(self.urls_on_current_page)
        r = self.client.get(url)

class AwesomeUser(HttpLocust):
    task_set = BrowseDocumentation
    host = "http://docs.locust.io/en/latest/"
    # we assume someone who is browsing the Locust docs, 
    # generally has a quite long waiting time (between 
    # 20 and 600 seconds), since there's a bunch of text 
    # on each page
    min_wait = 20  * 1000
    max_wait = 600 * 1000
$ locust -f locustfile.pyRead more in documentation »


  1. Jonatan Heyman

  2. Carl Byström

  3. Joakim Hamrén

  4. Hugo Heyman


A large portion of Locust has been developed at ESN, a company specialized in making large scale social web sites and software for real-time web development.