Locust 安装完整指南：pip 与 uvx 两种安装路径、预发布构建与常见安装问题排查

Locust 安装完整指南pip 与 uvx 两种安装路径、预发布构建与常见安装问题排查【免费下载链接】locustWrite scalable load tests in plain Python 项目地址: https://gitcode.com/gh_mirrors/lo/locust本文基于 Locust 官方安装文档 installation.rst 整理并深入展开覆盖 Locust 从 Python 环境准备、标准 pip 安装、验证安装、uvx 临时环境安装到预发布pre-release开发版安装与开发者安装方式的全部流程。读完本文你将能够独立完成 Locust 的部署与验证理解其版本与依赖在源码中的落点并掌握Python.h缺失、wheel 构建失败、locust命令不在 PATH、文件描述符上限等典型安装问题的诊断与解决办法。一、前置条件Python 版本要求Locust 官方安装流程的第一步是确认本机已安装 Python。版本约束直接定义在项目的打包配置 pyproject.toml 中requires-python 3.11即 Locust 当前要求 Python 3.11 及以上版本。结合同一文件中声明的 Python 版本分类器Python 3.11 至 3.15与 CI 测试矩阵[tool.hatch.envs.test.matrix]中覆盖 3.11~3.15可以确认当前版本 Locust 在这些 Python 版本上均有测试保障。如果本机尚未安装 Python需要先完成 Python 安装然后再进入下一步。二、标准安装pip 安装 Locust安装命令只有一行$ pip install locust验证安装安装完成后运行$ locust -V locust |version| from /usr/local/lib/python3.12/site-packages/locust (Python 3.12.5)输出形如locust 版本号 from locust 包所在目录 (Python Python 版本)即表示安装成功。这里有两处源码细节值得说明-V参数的实现。在 argument_parser.py 中Locust 手动注册了--version/-V选项源码注释说明这是为了同时获得短选项-V其输出格式字符串为versionflocust {version} from {os.path.dirname(__file__)} (Python {platform.python_version()})与文档示例输出完全对应locust后跟版本号from后是包安装目录括号内是运行时 Python 版本。此外argument_parser.py 中还存在一个“早期解析器”在加载 locustfile 之前Locust 会先用一个只识别-f/-h/--version的精简 parser 预扫描命令行确保locust -V这类请求在加载用户测试文件之前就能快速返回版本信息。版本号的来源。Locust 包不维护静态版本号而是通过 hatch-vcs 从 git 标签推导。见 pyproject.toml[tool.hatch.version] source vcs [tool.hatch.build.hooks.vcs] version-file locust/_version.py构建时会生成locust/_version.py运行时由 locust/init.py 的from ._version import version as __version__读入。官方文档构建时conf.py 中的.. |version| replace:: {__version__}替换指令会把文档里的|version|占位符渲染为实际版本号——这就是上面示例输出中出现|version|字样的原因。三、使用 uvx 安装替代方案如果偏好 uv 生态可以先安装 uv然后用uvx在临时ephemeral隔离环境中直接运行 Locust无需预先创建虚拟环境或污染全局 Python$ uvx locust -V locust |version| from /.../uv/.../locust (Python 3.12.5)uvx会按需拉取 locust 及其全部依赖到一次性环境中执行适合快速体验、CI 探针或不想管理虚拟环境的场景。验证方式同样是-V打印版本。四、安装预发布pre-release构建如果你需要最新功能而无法等待正式版本可以安装开发版构建$ pip3 install -U --pre locust--pre允许 pip 选择预发布版本-U确保升级到最新。官方说明这类构建在每次分支/PR 合入 master 时都会发布因此预发布构建基本等价于“master 分支的即时快照”。对应的版本策略可以在 pyproject.toml 中看到local_scheme no-local-version即预发布包不带 git 哈希这类 local 后缀保证pip install --pre安装出的版本号干净可读。仓库 CHANGELOG.md 顶部的条目如 2.46.3可用于确认当前发布线所处的版本区间。五、安装 Locust 究竟装了什么依赖与入口解析“锦上添花”地理解依赖清单有助于在排障时判断问题出在哪一层。pyproject.toml 声明的核心依赖包括依赖作用flask/WerkzeugWeb UI 与 REST API 的 HTTP 框架gevent24.10.1协程并发模型含 C 扩展需编译/取二进制轮geventhttpclient2.3.1高性能 HTTP 客户端FastHttpUser的底座C 扩展pyzmq25.0.0分布式 Master/Worker 的 ZeroMQ 通信requests2.32.2HttpUser使用的同步风格 HTTP 客户端psutil5.9.1系统资源监控C 扩展msgpack、configargparse、Flask-Login、Flask-Cors消息序列化、命令行/配置文件解析、Web 认证与跨域python-socketio[client]、python-engineio实时通信协议支持pytest8.3.3,10支持 pytest 风格 locustfilepywin32; sys_platform win32仅 Windows 平台安装用于系统级集成此外还有一组可选 extraspyproject.tomlmqttpaho-mqtt、dnsdnspython、milvus、qdrant、otelOpenTelemetry SDK 与 exporter等对应 locust/contrib/ 下的各协议模块按需安装即可例如pip install locust[mqtt]。命令行入口locust由 pyproject.toml 中的 console script 注册[project.scripts] locust locust.main:main也就是说locust命令最终调用的是 main.py 中的main()先加载 locustfile、合并 User 类再解析全部命令行参数并打印Starting Locust {version}启动日志。另一个关键细节在 locust/init.py只要未设置LOCUST_SKIP_MONKEY_PATCH环境变量import locust就会立即执行 gevent 的monkey.patch_all()。这解释了为什么 locustfile 中必须第一个导入locustruff 的 isort 配置专门为此设了独立 section见 pyproject.toml 的注释也是排障时需要了解的基础行为。六、用于开发目的的安装如果要修改 Locust 本身或参与贡献参见 developing-locust.rst# clone 你 fork 的仓库后在项目根目录 $ uv venv $ . .venv/bin/activate $ uv sync # 可编辑安装 locust 包及开发/测试依赖组uv sync会按 pyproject.toml 的[dependency-groups]build、test、lint 等安装完整开发依赖之后无需重装即可运行你自己的改动。测试与 lint 通过 hatch 驱动hatch test全矩阵或pytest locust/test直接跑单个套件如pytest locust/test/test_main.py。七、安装问题排查Troubleshooting以下是官方安装文档给出的常见故障及处置方案按错误特征索引。7.1psutil/_psutil_common.c:9:10: fatal error: Python.h: No such file or directory原因编译 C 扩展时找不到 Python 头文件说明当前 Python 缺少开发头文件包Linux 上通常是python3-dev/python3-devel一类包。处置安装对应 Python 版本头文件开发包后重试官方文档中该问题有对应的 Stack Overflow 讨论可作为参考线索。7.2ERROR: Failed building wheel for xxxLocust 本身是纯 Python 包但它依赖的gevent、geventhttpclient等包含从 C 代码编译的组件。绝大多数主流平台在 PyPI 上都有二进制轮wheel但偶尔新版缺少二进制轮或者你在一个冷门平台上就会退回到源码编译并报错。官方给出三条出路macOS安装 Xcode 命令行工具xcode-select --install使用pip install --prefer-binary locust即使存在更新的源码版本也优先选择预编译的包版本针对实际失败的那个包不是 Locust检索其报错信息确认构建工具链编译器、头文件是否齐备7.3 Windows 平台Windows 上的安装问题在官方文档中指向了专门的社区讨论Stack Overflow 相关线程。从打包配置看Windows 是一个被显式支持的分支依赖清单中带有pywin32; sys_platform win32的平台条件依赖说明 Windows 下安装时会额外引入 pywin32 提供系统级能力。排障时若与 pywin32 或编译工具链相关优先检查 VS Build Tools 与 Visual C 组件是否完整。7.4 安装成功但locust命令找不到回顾 pip 安装输出是否出现过类似警告The script locust is installed in ... which is not on PATH这说明 console script对应 pyproject.toml 中的locust locust.main:main入口被写入了一个不在PATH中的目录典型如用户级~/.local/bin。处置把该目录加入PATH环境变量或在非交互 shell/CI 中显式调用python -m locustLocust 提供main.py 支持模块方式运行。7.5 提升最大打开文件数限制ulimit每个 Locust 模拟用户、每条 HTTP 连接都会打开一个新文件严格说是文件描述符。许多操作系统默认的 fd 上限很低。Locust 会尝试自动调整该限制但很多系统不允许运行时提限此时日志中会出现相应告警需要手工调整调整方式因操作系统而异通用思路是修改系统的文件描述符限制sysctl/limits 配置等基于 systemd 的系统如 Debian/Ubuntu对图形登录会话使用不同的限制层级需要在 systemd 侧如LimitNOFILE额外设置否则图形会话里启动 Locust 仍受低限制约束。这一限制在大规模压测高并发用户数场景下尤其关键未提前调高 fd 上限分布式或单机的 headful 压测可能因为连接无法建立而出现大量失败请求。八、小结与下一步常规用户Python ≥ 3.11 pip install locustlocust -V验证三步完成快速试用/隔离环境uvx locust -V追新pip3 install -U --pre locustmaster 合入即发布参与开发fork uv venvuv sync用hatch test/pytest locust/test跑测试遇到报错按本文第七节的错误特征Python.h缺失、Failed building wheel、-V找不到、fd 上限告警逐一对照处置。安装验证通过后即可按 quickstart.rst 编写并运行你的第一个测试仓库中 examples/basic.py 提供了最小可运行的示例 locustfile若选择容器化部署可参考 running-in-docker.rst。【免费下载链接】locustWrite scalable load tests in plain Python 项目地址: https://gitcode.com/gh_mirrors/lo/locust创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考