Locust

intermediate

Scalable load testing framework in Python.

Overview

Locust is an open-source, Python-based load testing framework that revolutionizes performance testing by allowing developers to define user behavior through simple Python code instead of complex GUI configurations or XML files. Created by Carl Byström and later adopted by the open-source community, Locust has become the go-to choice for teams seeking scriptable, maintainable load tests that can scale from single-machine tests to distributed swarms generating millions of concurrent users. This Docker stack implements a distributed Locust architecture with a master node orchestrating multiple worker nodes, enabling horizontal scaling of load generation across multiple containers. The master node serves the web interface and coordinates test execution, while worker nodes execute the actual load generation tasks, distributing the computational overhead across multiple processes. This distributed approach allows teams to generate significantly more load than single-instance testing tools while maintaining precise control over test scenarios through Python scripting. Development teams working with Python-heavy tech stacks, performance engineers conducting large-scale load tests, and DevOps teams integrating performance testing into CI/CD pipelines will find this configuration particularly valuable. The combination provides enterprise-grade load testing capabilities with the flexibility of Python scripting, making it ideal for testing complex user journeys, API endpoints, and custom protocols that require programmatic test logic.

Key Features

Python-based test scripts with full programming language flexibility for complex user scenarios
Web-based real-time dashboard showing RPS, response times, and failure rates during test execution
Distributed load generation with master-worker architecture for horizontal scaling
Live statistics and charts updating during test runs without stopping execution
Support for HTTP, WebSocket, gRPC and custom protocol testing through Python libraries
Built-in user simulation with realistic think times and session management
Extensible architecture with custom listeners and events for specialized reporting
RESTful API for programmatic test control and integration with CI/CD pipelines

Common Use Cases

1API load testing for microservices architectures with complex authentication flows
2E-commerce platform performance testing simulating realistic shopping cart and checkout scenarios
3Gaming server load testing with custom protocols and real-time connection simulation
4CI/CD pipeline integration for automated performance regression testing
5Multi-tenant SaaS application testing with tenant-specific user behavior patterns
6WebSocket and real-time application testing for chat systems and live updates
7Load testing behind corporate firewalls using Python HTTP libraries with custom authentication

Prerequisites

Minimum 1GB RAM for master node, additional 512MB per worker for meaningful load generation
Python knowledge for writing and maintaining locustfile.py test scenarios
Understanding of HTTP protocols, status codes, and web application architecture
Network access to target systems being tested with appropriate firewall configurations
Port 8089 available for Locust web interface access
Docker host with sufficient CPU cores to support multiple worker containers effectively

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  master: 
3    image: locustio/locust:latest
4    container_name: locust-master
5    restart: unless-stopped
6    command: -f /locust/locustfile.py --master -H http://target:8080
7    volumes: 
8      - ./locustfile.py:/locust/locustfile.py:ro
9    ports: 
10      - "8089:8089"
11
12  worker: 
13    image: locustio/locust:latest
14    restart: unless-stopped
15    command: -f /locust/locustfile.py --worker --master-host master
16    volumes: 
17      - ./locustfile.py:/locust/locustfile.py:ro
18    depends_on: 
19      - master
20    deploy: 
21      replicas: 4

.env Template

.env

1# Create locustfile.py with your load tests

Usage Notes

1Docs: https://docs.locust.io/
2Web UI at http://localhost:8089 - configure users and spawn rate
3Write test scenarios in Python (locustfile.py)
4Scale with workers: docker-compose up --scale worker=10
5Real-time charts for RPS, response times, failures
6HTTP and custom protocol support (WebSocket, gRPC)

Individual Services(2 services)

Copy individual services to mix and match with your existing compose files.

master

master:
  image: locustio/locust:latest
  container_name: locust-master
  restart: unless-stopped
  command: "-f /locust/locustfile.py --master -H http://target:8080"
  volumes:
    - ./locustfile.py:/locust/locustfile.py:ro
  ports:
    - "8089:8089"

worker

worker:
  image: locustio/locust:latest
  restart: unless-stopped
  command: "-f /locust/locustfile.py --worker --master-host master"
  volumes:
    - ./locustfile.py:/locust/locustfile.py:ro
  depends_on:
    - master
  deploy:
    replicas: 4

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  master:
5    image: locustio/locust:latest
6    container_name: locust-master
7    restart: unless-stopped
8    command: -f /locust/locustfile.py --master -H http://target:8080
9    volumes:
10      - ./locustfile.py:/locust/locustfile.py:ro
11    ports:
12      - "8089:8089"
13
14  worker:
15    image: locustio/locust:latest
16    restart: unless-stopped
17    command: -f /locust/locustfile.py --worker --master-host master
18    volumes:
19      - ./locustfile.py:/locust/locustfile.py:ro
20    depends_on:
21      - master
22    deploy:
23      replicas: 4
24EOF
25
26# 2. Create the .env file
27cat > .env << 'EOF'
28# Create locustfile.py with your load tests
29EOF
30
31# 3. Start the services
32docker compose up -d
33
34# 4. View logs
35docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/locust/run | bash

Troubleshooting

Workers not connecting to master: Verify master container name resolution and ensure --master-host points to correct service name
High memory usage during tests: Reduce user spawn rate, decrease worker replicas, or increase host memory allocation
ImportError in locustfile.py: Install required Python packages by building custom Docker image with additional dependencies
Target connection refused errors: Verify target application is accessible from Docker network and correct hostname/port specified
Web UI shows zero RPS despite running test: Check locustfile.py syntax errors and verify task decorators are properly defined
SSL certificate errors when testing HTTPS endpoints: Add verify=False parameter to requests or mount custom certificates

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

locust

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download