Installation

Note

Check Troubleshooting Installation if you encounter issues.

  1. Install Python (if you dont already have it)

  2. Install Locust

$ pip3 install locust
  1. Validate your installation

$ locust -V
locust 2.32.5 from /usr/local/lib/python3.12/site-packages/locust (Python 3.12.5)

Using uvx (alternative)

  1. Install uv

  2. Install and run locust in an ephemeral environment

$ uvx locust -V
locust 2.32.5 from /.../uv/.../locust (Python 3.12.5)

Done!

Now you can create and run your first test


Pre-release builds

If you need the latest and greatest version of Locust and cannot wait for the next release, you can install a dev build like this:

$ pip3 install -U --pre locust

Pre-release builds are published every time a branch/PR is merged into master.

Install for development

If you want to modify Locust, or contribute to the project, see Developing and Documenting Locust.

Troubleshooting installation

psutil/_psutil_common.c:9:10: fatal error: Python.h: No such file or directory

Answered in Stackoverflow thread 63440765

ERROR: Failed building wheel for xxx

While Locust itself is a pure Python package, it has some dependencies (e.g. gevent and geventhttpclient) that are compiled from C code. Pretty much all common platforms have binary packages on PyPi, but sometimes there is a new release that doesn’t, or you are running on some exotic platform. You have two options:

  • (on macos) Install xcode: xcode-select --install

  • Use pip install --prefer-binary locust to select a pre-compiled version of packages even if there is a more recent version available as source.

  • Try googling the error message for the specific package that failed (not Locust), ensure you have the appropriate build tools installed etc.

Windows

Answered in Stackoverflow thread 61592069

Installation works, but the locust command is not found

When running pip, did you get a warning saying The script locust is installed in '...' which is not on PATH?

Add that directory to your PATH environment variable.

Increasing Maximum Number of Open Files Limit

Every User/HTTP connection from Locust opens a new file (technically a file descriptor). Many operating systems by default set a low limit for the maximum number of files that can be open at the same time. Locust will try to adjust this automatically for you, but in a lot of cases your operating system will not allow it (in which case you will get a warning in the log). Instead you will have to do it manually.

How to do this depends on your operating system, but you might find some useful information here: https://www.tecmint.com/increase-set-open-file-limits-in-linux/ and practical examples https://www.ibm.com/support/knowledgecenter/SS8NLW_11.0.2/com.ibm.discovery.es.in.doc/iiysiulimits.html

For systemd-based systems (e.g. Debian/Ubuntu) different limits are used for graphical login sessions. See https://unix.stackexchange.com/a/443467 for additional settings.