Running Locust with Docker

To keep things simple we provide a single Docker image that can run standalone, as a master, or as a slave.

Environment Variables


One of ‘standalone’, ‘master’, or ‘slave’. Defaults to ‘standalone’.


The path inside the container to the locustfile. Defaults to ‘/’


The hostname of the master.


The port used to communicate with the master. Defaults to 5557.


Additional options to pass to locust. Defaults to ‘’

Running your tests

The easiest way to get your tests running is to build an image with your test file built in. Once you’ve written your locustfile you can bake it into a Docker image with a simple Dockerfile:

You’ll need to push the built image to a Docker repository such as Dockerhub, AWS ECR, or GCR in order for distributed infrastructure to be able to pull the image. See your chosen repository’s documentation on how to authenticate with the repository to pull the image.

For debugging locally you can run a container and pass your locustfile in as a volume:

To run in standalone mode without the web UI, you can use the LOCUST_OPTS environment variable to add the required options:

If you are Kubernetes user, you can use the Helm chart to scale and run locust.