Locust は Python で負荷テストシナリオを書けるオープンソースツールです。locustfile.py に @task デコレータでリクエストを定義するだけで、数十〜数千ユーザーの同時アクセスをシミュレートできます。ブラウザで動くWeb UIとCLIのヘッドレスモードを両方持っているので、「手で確認したい」と「CIで回したい」のどちらにも対応します。
この記事では Ubuntu 24.04 LTS に Locust 2.44.4 をインストールし、Flask のテストサーバーに対して実際に負荷テストを実行した結果を載せます。
この記事のポイント
- Ubuntu 24.04 では
pip install locustを直接実行すると PEP 668 エラーになる——必ずpython3 -m venvで仮想環境を作ってから入れる @task(weight)の数字で「どのエンドポイントに何割アクセスするか」を比率で指定できる- 実測: 20ユーザー / 15秒で 270 リクエスト、エラー率 0%、スループット 19.4 req/s
- ヘッドレスモード（
--headless）で UI なしのバッチ実行・CSV出力が可能 - Web UI はデフォルト
localhost:8089で立ち上がり、リアルタイムでグラフを確認できる
動作確認済み環境
| 項目 | バージョン・詳細 |
|---|---|
| OS | Ubuntu 24.04 LTS（Noble Numbat） |
| Python | Python 3.12.3（Docker ubuntu:24.04 実測） |
| Locust | 2.44.4（pip install / 2026-06-22） |
| 実行環境 | docker run ubuntu:24.04 / ホスト直接インストール |
インストール手順
手順1：システムパッケージを更新する
まず apt でリポジトリ情報を更新し、Python 関連のパッケージを入れます。
Hit:1 http://archive.ubuntu.com/ubuntu noble InRelease
Reading package lists… Done
$ sudo apt install -y python3 python3-venv python3-pip
Setting up python3-venv (3.12.3-0ubuntu2) …
Setting up python3-pip (24.0+dfsg-1ubuntu1) …
$ python3 –version
Python 3.12.3
手順2：仮想環境（venv）を作って Locust をインストールする
Ubuntu 24.04 では PEP 668 の制限により、システムの Python に直接 pip install するとエラーになります。必ず python3 -m venv で仮想環境を作ってから入れてください。正直、最初にこれで詰まりました。
注意：Ubuntu 24.04 で pip install が通らない場合
error: externally-managed-environment と表示されたら PEP 668 によるブロックです。--break-system-packages を使うとシステムの Python が壊れるリスクがあります。必ず venv を使ってください。
$ source locust-env/bin/activate
(locust-env) $
(locust-env) $ pip install locust
Collecting locust
Downloading locust-2.44.4-py3-none-any.whl
Installing collected packages: gevent, flask, … locust
Successfully installed locust-2.44.4
(locust-env) $ locust –version
locust 2.44.4 from locust-env/lib/python3.12/site-packages/locust (Python 3.12.3)
インストール時に flask、gevent、geventhttpclient、python-socketio など Web UI と分散実行に必要なパッケージが一緒に入ります。
locustfile.py の書き方
Locust は locustfile.py というファイルにテストシナリオを定義します。最小構成は次のとおりです。
class APIUser(HttpUser):
wait_time = between(0.5, 1.5) # リクエスト間の待ち時間（秒）
host = “http://localhost:5000”
@task(3) # 全体の 3/8 の割合で実行
def index(self):
self.client.get(“/”)
@task(2) # 全体の 2/8
def api_users(self):
self.client.get(“/api/users”)
@task(2) # 全体の 2/8（重めのエンドポイントを同比率でテスト）
def api_search(self):
self.client.get(“/api/search”)
@task(1) # 全体の 1/8（最低頻度）
def api_health(self):
self.client.get(“/api/health”)
ポイントは @task の括弧内の数字です。@task(3)、@task(2)、@task(2)、@task(1) を並べると、3:2:2:1 の比率で各タスクが実行されます。実際の API の使われ方に近い比率に合わせると、より実態に即したテストになります。
Web UI でテストを実行する
locust コマンドを引数なしで実行すると、ブラウザで操作できる Web UI が起動します。
[INFO/locust.main] Starting Locust 2.44.4
[INFO/locust.main] Starting web interface at http://0.0.0.0:8089
ブラウザで http://localhost:8089 を開いてください
①起動直後の設定画面
ブラウザで http://localhost:8089 を開くと、ユーザー数とスポーンレートを設定する画面が表示されます。
「Number of users」に同時接続ユーザー数、「Spawn rate」に1秒あたりの増加人数を入れて「Start」を押します。今回は 10 ユーザー、スポーンレート 2 で実行しました。
②テスト実行中のダッシュボード
テストが始まるとリアルタイムでリクエスト数・レスポンスタイム・エラー数が更新されます。
③Charts ビュー
上部タブの「Charts」を選ぶと、スループット（req/s）・レスポンスタイム・同時ユーザー数の推移グラフをリアルタイムで確認できます。
「Stop」ボタンを押してテストを止めると、最終集計が画面に残ります。「Download Data」からCSVレポートをダウンロードすることもできます。
ヘッドレスモードで自動実行する
CI/CDパイプラインや定期実行では --headless フラグを使います。ブラウザを開かずにテストを走らせ、結果を CSV に保存できます。
–headless \
–users 20 \
–spawn-rate 5 \
–run-time 15s \
–csv result \
–host http://localhost:5000
[INFO/locust.main] Starting Locust 2.44.4
[INFO/locust.runners] Ramping to 20 users at a rate of 5.00 per second
Type Name # reqs # fails | Avg Min Max Med | req/s
GET / 87 0 | 1 0 3 1 | 6.25
GET /api/users 77 0 | 1 0 9 1 | 5.53
GET /api/search 67 0 | 8 4 11 8 | 4.81
GET /api/health 39 0 | 1 0 4 1 | 2.80
Aggregated 270 0 | 2 0 11 2 | 19.38
実測値：20ユーザー・15秒で 270リクエスト、エラー率 0%、スループット 19.4 req/s。レスポンスタイムの中央値は 2ms（/api/search は sleep 処理を含むため 8ms）でした。
実測結果：エンドポイント別の詳細統計
ヘッドレステストで取得した CSV データを集計した結果です。
注目点は /api/search のレスポンスタイムです。意図的に 3〜10ms の遅延を入れていたためで、中央値が他のエンドポイントの 5 倍になっています。実際のサービスでも「遅いエンドポイントを特定してボトルネックを探る」という使い方がよくあります。
Ubuntu 22.04 と 24.04 のインストール方法の違い
Ubuntu 22.04（Jammy）では pip3 install locust が venv なしでも通りますが、24.04（Noble）からは PEP 668 の施行で venv が事実上必須になりました。新規サーバーを立てるなら 24.04 + venv の組み合わせを選ぶのが今後の標準になります。
よくあるエラーと解決策
error: externally-managed-environment
error: externally-managed-environment
× This environment is externally managed
To install packages, use python3 -m venv and pip inside it.
Ubuntu 24.04 特有のエラーです。python3 -m venv locust-env && source locust-env/bin/activate を先に実行してから pip install locust を実行してください。
Connection refused（Web UI に繋がらない）
Locust のプロセスが起動していない、またはポートが別アプリに使われています。
LISTEN 0 128 0.0.0.0:8089 0.0.0.0:* users:((“locust”,…))
# 何も表示されなければ Locust が起動していない
$ locust -f locustfile.py –web-port 8090 # ポートを変える場合
No module named ‘locust’（venv 外で実行した）
仮想環境を有効化せずに locust コマンドを叩くと発生します。source locust-env/bin/activate を実行してから試してください。
仮想環境の有効化を忘れやすいポイント
ターミナルを開き直すたびに source locust-env/bin/activate が必要です。(.env) という表示がプロンプトに出ていれば有効化済みです。
まとめ
Ubuntu 24.04 への Locust セットアップの流れをまとめます。
- Ubuntu 24.04 では venv を作ってから
pip install locustする（PEP 668 のため） locustfile.pyにHttpUserクラスを定義し、@task(weight)でシナリオを書く- Web UI（
localhost:8089）で GUI 操作、--headlessで CLI 実行 - ヘッドレスモードで
--csv resultを付けると詳細な統計 CSV が出力される - 実測: 20ユーザー・15秒で 270 リクエスト、エラー率 0%、スループット 19.4 req/s
VPS でテスト対象の API を動かしているなら、Locust を別のサーバーから実行すると実際のネットワーク遅延も含めた測定ができます。
本格的な負荷テスト環境を VPS に構築するなら、 も参考にしてください。
コメント