{"library":"locust","title":"Locust","description":"Locust is an open-source, developer-friendly load testing framework that allows you to define user behavior in plain Python code. It's designed for testing web applications, APIs, and other systems, supporting hundreds of thousands of concurrent users through its event-based architecture. Locust offers a real-time web-based UI for monitoring and analysis, and is actively maintained with frequent updates (approximately every 62 days) [1, 2, 11, 19, 31]. It currently requires Python 3.10 or newer [31].","status":"active","version":"2.43.4","language":"en","source_language":"en","source_url":"https://github.com/locustio/locust","tags":["load testing","performance testing","web testing","stress testing","api testing"],"install":[{"cmd":"pip install locust","lang":"bash","label":"Standard installation"}],"dependencies":[{"reason":"Requires Python 3.10 or newer for current versions.","package":"python","optional":false},{"reason":"Core dependency for asynchronous operations, often requires C build tools for compilation on some systems.","package":"gevent","optional":false},{"reason":"Alternative, higher-performance HTTP client for HttpUser, often requires C build tools for compilation on some systems.","package":"geventhttpclient","optional":false}],"imports":[{"note":"`HttpLocust` was renamed to `HttpUser` in version 2.0.0 [25, 29].","wrong":"from locust import HttpLocust","symbol":"HttpUser","correct":"from locust import HttpUser"},{"note":"Used as a decorator for methods within `User` or `HttpUser` classes to define user actions [20].","symbol":"task","correct":"from locust import task"},{"note":"A built-in wait_time function for simulating realistic user think times [20].","symbol":"between","correct":"from locust import between"},{"note":"The base `Locust` class was renamed to `User` in version 2.0.0 [25, 29]. `HttpUser` is typically used for web testing [20, 21].","wrong":"from locust import Locust","symbol":"User","correct":"from locust import User"}],"quickstart":{"code":"import os\nfrom locust import HttpUser, task, between\n\nclass QuickstartUser(HttpUser):\n    wait_time = between(1, 2)  # Users wait between 1 and 2 seconds after each task\n    host = os.environ.get('LOCUST_TARGET_HOST', 'http://localhost:8089') # Default host for testing\n\n    def on_start(self):\n        \"\"\" on_start is called when a Locust user starts running \"\"\"\n        # Example: Simulating a login if required by the target system\n        # self.client.post(\"/login\", json={\"username\":\"test_user\", \"password\":\"test_password\"})\n        print(f\"Starting user on host: {self.host}\")\n\n    @task\n    def hello_world(self):\n        self.client.get(\"/hello\")\n        self.client.get(\"/world\")\n\n    @task(3)\n    def view_items(self):\n        # Simulate viewing items with dynamic IDs, using 'name' to aggregate stats\n        for item_id in range(10):\n            self.client.get(f\"/item?id={item_id}\", name=\"/item\")\n\n    def on_stop(self):\n        \"\"\" on_stop is called when a Locust user stops running \"\"\"\n        # Example: Simulating a logout\n        # self.client.post(\"/logout\")\n        print(\"Stopping user.\")\n\n# To run this, save as `locustfile.py` and execute `locust` from the terminal.\n# Then open your browser to http://localhost:8089 to use the web UI.\n# Alternatively, run headless: `locust -f locustfile.py --headless --users 10 --spawn-rate 5 -H http://your-target-host.com`","lang":"python","description":"This quickstart defines a `QuickstartUser` that inherits from `HttpUser` for HTTP load testing. It includes `wait_time` to simulate user think time and two tasks (`hello_world` and `view_items`) decorated with `@task` to define user actions. The `view_items` task demonstrates using the `name` parameter for grouping dynamic URLs. `on_start` and `on_stop` methods are shown for per-user setup and teardown, such as login/logout. Save this code as `locustfile.py` and run `locust` from the command line to start the web UI, or use the `--headless` option for command-line execution [2, 10, 20]."},"warnings":[{"fix":"Update imports from `from locust import HttpLocust` to `from locust import HttpUser`. Similarly, `Locust` becomes `User` [25, 29].","message":"The primary user classes `Locust` and `HttpLocust` were renamed to `User` and `HttpUser` respectively in version 2.0.0. Older scripts using `HttpLocust` will fail.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Replace `min_wait = X` and `max_wait = Y` with `wait_time = between(X, Y)`. For custom logic, define a `wait_time` method on your `User` class [20, 27].","message":"The `min_wait`, `max_wait`, and `wait_function` attributes on `User` classes are deprecated. Use the `wait_time` attribute instead, which should be set to a function (like `between`, `constant`, `constant_throughput`) or a custom callable [27].","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"For requests like `self.client.get(f'/item?id={item_id}')`, add `name='/item'` (e.g., `self.client.get(f'/item?id={item_id}', name='/item')`) to group statistics under a common label [20, 21, 36].","message":"When testing URLs with dynamic components (e.g., `/item?id=1`, `/item?id=2`), Locust will, by default, record each unique URL separately in statistics. This can lead to an explosion of metrics and make analysis difficult. To aggregate these, use the `name` parameter in your client request.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Call `self.interrupt()` within a `TaskSet` method to explicitly exit the `TaskSet` and allow the user to pick other tasks from its parent [22, 24, 26].","message":"The `TaskSet` class (an advanced feature for grouping tasks) does not automatically return control to its parent `User` or `TaskSet`. If not explicitly interrupted, a user entering a `TaskSet` will remain executing its tasks indefinitely.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that Python development headers and a C compiler (e.g., build-essential on Linux, Xcode command line tools on macOS, Visual C++ Build Tools on Windows) are installed. Using `pip install --prefer-binary locust` can sometimes help by forcing the use of pre-compiled wheels if available [16, 30].","message":"Locust has dependencies like `gevent` and `geventhttpclient` which are compiled from C code. This can lead to installation failures if the necessary build tools (e.g., C compiler, Python development headers) are not present on the system.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your test script is named `locustfile.py` or specify the filename using the `-f` flag when running Locust (e.g., `locust -f my_test_script.py`) [4, 9].","message":"By default, Locust looks for a test script named `locustfile.py`. If your script has a different name, or is not in the current directory, Locust will not find it.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always add assertions to validate the response content, not just the status code. Use Python's built-in assertion capabilities on `response.text` or `response.json()` and call `response.failure(\"Reason for failure\")` if validation fails [34].","message":"Only checking HTTP status codes (e.g., 200 OK) is often insufficient for validating successful user flows. A server might return 200 OK with an error message in the body, or simply not return the expected content.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-06T00:00:00.000Z","next_check":"2026-07-05T00:00:00.000Z"}