Increase Locust’s performance with a faster HTTP client

Locust’s default HTTP client uses python-requests. The reason for this is that requests is a very well-maintained python package, that provides a really nice API, that many python developers are familiar with. Therefore, in many cases, we recommend that you use the default HttpUser which uses requests. However, if you’re planning to run really large scale tests, Locust comes with an alternative HTTP client, FastHttpUser which uses geventhttpclient instead of requests. This client is significantly faster, and we’ve seen 5x-6x performance increases for making HTTP-requests. This does not necessarily mean that the number of users one can simulate per CPU core will automatically increase 5x-6x, since it also depends on what else the load testing script does. However, if your locust scripts are spending most of their CPU time in making HTTP-requests, you are likely to see significant performance gains.

It is impossible to say what your particular hardware can handle, but in a best case scenario you should be able to do close to 5000 requests per second per core, instead of around 850 for the normal HttpUser (tested on a 2018 MacBook Pro i7 2.6GHz)

How to use FastHttpUser

Subclass FastHttpUser instead of HttpUser:

from locust import task, between
from locust.contrib.fasthttp import FastHttpUser

class MyUser(FastHttpUser):
    wait_time = between(2, 5)

    def index(self):
        response = self.client.get("/")


Because FastHttpUser uses a different client implementation with a slightly different API, it may not always work as a drop-in replacement for HttpUser.


FastHttpUser class

class FastHttpUser(environment)

FastHttpUser uses a different HTTP client (geventhttpclient) compared to HttpUser (python-requests). It’s significantly faster, but not as capable.

The behaviour of this user is defined by it’s tasks. Tasks can be declared either directly on the class by using the @task decorator on the methods, or by setting the tasks attribute.

This class creates a client attribute on instantiation which is an HTTP client with support for keeping a user session between requests.

connection_timeout: float = 60.0

Parameter passed to FastHttpSession

insecure: bool = True

Parameter passed to FastHttpSession. Default True, meaning no SSL verification.

max_redirects: int = 5

Parameter passed to FastHttpSession. Default 5, meaning 4 redirects.

max_retries: int = 1

Parameter passed to FastHttpSession. Default 1, meaning zero retries.

network_timeout: float = 60.0

Parameter passed to FastHttpSession

FastHttpSession class

class FastHttpSession(environment, base_url, insecure=True, **kwargs)
get(path, **kwargs)

Sends a GET request

head(path, **kwargs)

Sends a HEAD request

options(path, **kwargs)

Sends a OPTIONS request

patch(path, data=None, **kwargs)

Sends a POST request

post(path, data=None, **kwargs)

Sends a POST request

put(path, data=None, **kwargs)

Sends a PUT request

request(method, path, name=None, data=None, catch_response=False, stream=False, headers=None, auth=None, json=None, allow_redirects=True, **kwargs)

Send and HTTP request Returns locust.contrib.fasthttp.FastResponse object.

  • method – method for the new Request object.

  • path – Path that will be concatenated with the base host URL that has been specified. Can also be a full URL, in which case the full URL will be requested, and the base host is ignored.

  • name – (optional) An argument that can be specified to use as label in Locust’s statistics instead of the URL path. This can be used to group different URL’s that are requested into a single entry in Locust’s statistics.

  • catch_response – (optional) Boolean argument that, if set, can be used to make a request return a context manager to work as argument to a with statement. This will allow the request to be marked as a fail based on the content of the response, even if the response code is ok (2xx). The opposite also works, one can use catch_response to catch a request and then mark it as successful even if the response code was not (i.e 500 or 404).

  • data – (optional) String/bytes to send in the body of the request.

  • json – (optional) Dictionary to send in the body of the request. Automatically sets Content-Type and Accept headers to “application/json”. Only used if data is not set.

  • headers – (optional) Dictionary of HTTP Headers to send with the request.

  • auth – (optional) Auth (username, password) tuple to enable Basic HTTP Auth.

  • stream – (optional) If set to true the response body will not be consumed immediately and can instead be consumed by accessing the stream attribute on the Response object. Another side effect of setting stream to True is that the time for downloading the response content will not be accounted for in the request time that is reported by Locust.

class FastResponse(ghc_response, request=None, sent_request=None)
property content

Unzips if necessary and buffers the received body. Careful with large files!


Dict like object containing the response headers


Parses the response as json and returns a dict

property text

Returns the text content of the response as a decoded string