How to Install Locust in Python

Load testing tells you how your application behaves under pressure. Locust is one of the easiest tools for the job because you write tests in plain Python.

Installing Locust takes only a few minutes. This guide walks through every step, from preparing your environment to running your first test.

You will also learn how to verify the installation, troubleshoot common errors, and avoid the mistakes that trip up beginners.

What Is Locust?

Locust is an open-source load testing framework written in Python. It lets you define user behavior in code and simulate thousands of concurrent users.

Unlike older tools that rely on XML or GUI configuration, Locust uses Python classes and methods. That means you can use loops, conditionals, and any Python library in your tests.

The tool scales horizontally across multiple machines. It also provides a real-time web interface for monitoring test execution.

Whether you are testing a REST API, a web app, or a custom protocol, Locust gives you full control over the load scenario.

Prerequisites

Before you install Locust, make sure your system meets these requirements.

• Python 3.10 or later. Newer Locust releases require a modern Python version.
• pip package manager. This comes bundled with most Python installations.
• A virtual environment. Recommended to keep dependencies isolated.
• A target application. You need something to test, even a local dev server.

Check your Python version with the command python --version. If pip is missing, run python -m ensurepip to install it.

Creating a virtual environment is good practice. It prevents Locust from interfering with your system packages.

 # Create a virtual environment python -m venv venv # Activate it on macOS or Linux source venv/bin/activate # Activate it on Windows venv\Scripts\activate 

Once activated, your terminal prompt changes to show the environment name. All packages you install now stay inside that folder.

How to Install Locust with pip

The standard installation method is pip. Run this command inside your activated virtual environment.

 pip install locust 

This downloads Locust and its dependencies from PyPI. The process usually takes less than a minute on a stable connection.

Some dependencies, like gevent and geventhttpclient, are compiled from C code. Most platforms have pre-built binary packages available.

If you run into build errors, try installing with the prefer-binary flag. This forces pip to use pre-compiled wheels instead of building from source.

 # Prefer pre-compiled wheels when available pip install --prefer-binary locust 

This single flag resolves most installation failures on Windows and older macOS systems.

Installing with uv

If you use uv, the modern Python package manager, you can install and run Locust without creating a permanent environment.

 # Install uv first if you do not have it pip install uv # Run Locust in an ephemeral environment uvx locust --version 

The uvx command downloads Locust into a temporary environment, runs it, and cleans up afterward. This is useful for quick tests on a fresh machine.

Verifying the Installation

After installation, confirm that Locust is available on your system. Run this command.

 locust --version 

You should see output similar to this.

 locust 2.32.3 

The exact version number may differ. What matters is that the command returns a version string without errors.

If you see a "command not found" message, the Locust script may not be on your PATH. Try running it as a Python module instead.

 python -m locust --version 

If that works, your installation is fine. You just need to add the Python scripts directory to your system PATH.

Keeping your imports tidy is also good practice. If you want to sort Python imports automatically with isort, you can set that up alongside your Locust project for cleaner test files.

Writing Your First Locust Test

Locust looks for a file named locustfile.py in your current directory. Create that file and add a simple test.

 # locustfile.py from locust import HttpUser, task, between class WebsiteUser(HttpUser): """Simulates a user browsing the website.""" # Wait 1 to 3 seconds between tasks wait_time = between(1, 3) @task def view_homepage(self): """Load the homepage.""" self.client.get("/") @task(3) def view_products(self): """Browse products page. Runs 3x more often.""" self.client.get("/products") 

The HttpUser class represents a simulated user. The @task decorator marks methods that Locust should execute.

The number inside @task(3) sets the relative weight. The products page runs three times more often than the homepage.

The wait_time attribute controls how long each simulated user pauses between tasks. This makes the load pattern more realistic.

Running Locust

Navigate to the folder containing your locustfile.py and start Locust.

 locust -f locustfile.py --host http://localhost:8000 

Locust starts a web interface on port 8089. Open your browser and go to http://localhost:8089.

Enter the number of users and the spawn rate, then click Start. Locust begins generating load and shows real-time statistics.

For automated tests or CI pipelines, run Locust in headless mode without the web interface.

 # Run 100 users for 5 minutes without the web UI locust -f locustfile.py \ --host http://localhost:8000 \ --users 100 \ --spawn-rate 10 \ --run-time 5m \ --headless 

The --headless flag disables the web interface. The --run-time flag stops the test automatically after the specified duration.

You can also export results to CSV files for later analysis.

 locust -f locustfile.py --host http://localhost:8000 \ --users 50 --spawn-rate 5 --run-time 2m \ --headless --csv results 

This generates results_stats.csv, results_failures.csv, and other files in your working directory.

Using Locust as a Python Library

You can also run Locust programmatically from another Python script. This is useful inside automation pipelines.

 import locust # Check the Locust version from Python print(locust.__version__) # The HttpUser class is the base for all HTTP-based tests from locust import HttpUser, task, between class ApiUser(HttpUser): wait_time = between(0.5, 2) @task def list_items(self): self.client.get("/api/items") 

The locust.__version__ attribute returns the installed version. The HttpUser class provides the self.client object for making HTTP requests.

If your load tests feed into a larger reporting workflow, you might pair Locust with a library that helps you generate PDFs with ReportLab in a Python guide. You can export test results as PDF reports for stakeholders.

Common Installation Problems

Problem: "Failed building wheel for gevent"

This means pip is trying to compile a C dependency from source. The fix is to use pre-built wheels.

 pip install --prefer-binary locust 

On macOS, you may also need to install Xcode command line tools with xcode-select --install.

Problem: "Python.h: No such file or directory"

This error appears on Linux when Python development headers are missing. Install them with your system package manager.

 # On Ubuntu or Debian sudo apt install python3-dev # On RHEL or Fedora sudo dnf install python3-devel 

Problem: "The script locust is installed in a directory not on PATH"

pip warns you when the Locust executable is not reachable from your shell. Add the reported directory to your PATH environment variable.

Problem: "Too many open files"

Locust opens a file descriptor for every simulated user connection. Operating systems often set a low limit by default. Raise the limit with ulimit -n 65536 on Linux or macOS.

Problem: Locust installs but crashes on startup

Check that your Python version is 3.10 or newer. Older versions are not supported by recent Locust releases.

If your test runs are part of a scheduled workflow, keep in mind that teams often schedule Python tasks with Airflow to run load tests automatically at regular intervals. Locust fits naturally into that kind of pipeline.

Best Practices for Locust Setup

Always use a virtual environment. This keeps Locust dependencies separate from your application packages.

Pin your Locust version. Use pip freeze > requirements.txt to lock the exact version. This ensures consistent behavior across machines.

Start small. Run your first test with one user and a single task. Verify that requests succeed before scaling up.

Use weighted tasks. Real users do not click every link equally. The @task weight system lets you model realistic traffic patterns.

Monitor resource usage. Locust itself consumes CPU and memory. On a single machine, a few thousand users may be the practical limit. Use distributed mode for larger tests.

Keep test files clean. As your locustfile.py grows, organize tasks into classes and modules. Clean imports make the file easier to maintain.

Conclusion

Installing Locust in Python is straightforward. Run pip install locust inside a virtual environment, verify with locust --version, and write your first locustfile.py.

The tool gives you full control over load scenarios because tests are written in Python. You can simulate simple HTTP requests or complex multi-step user flows.

Start with a small test against a local server. Scale up gradually as you learn how Locust behaves. Use the web interface for exploration and headless mode for automation.

With Locust installed, you have a powerful, flexible load testing tool ready whenever your application needs a stress test.