本記事では、pythonで進捗表示を行うライブラリであるtqdmの使い方を詳しく解説します。時間のかかる処理を行う際にプログレスバーがあると、作業の進行度合いをひと目で把握できて便利です。この記事を読めば、tqdmの基本的な使い方からカスタマイズ方法、応用事例まで一通りマスターできます。使い方を説明します。
tqdmとは
tqdmは、非常にシンプルな構文でプログレスバーを表示できるpythonのライブラリです。イテラブルオブジェクトをラップするだけでプログレスバーが出力され、長時間の反復処理やバッチ処理の進行状況を可視化できます。
公式GitHub: https://github.com/tqdm/tqdm
tqdmの基礎
インストール
pip install tqdm使いかた
tqdmはイテラブルをラップするだけでプログレスバーを表示してくれるので、for文で簡単に利用できます。
for文の詳しい説明は以下
from tqdm import tqdm
import time # 処理の時間をシミュレートするために使用
# tqdmで進捗状況を表示するループ
for i in tqdm(range(100)):
# 処理のシミュレーション (ここでは0.001秒のスリープ)
time.sleep(0.001)
# プログレスバーの表示
# 48%|███████████████████████████▏ | 4775/10000 [00:06<00:06, 789.34it/s]# strの配列を渡す例
from tqdm import tqdm
import time
text = ""
for char in tqdm(["a", "b", "c", "d"]):
time.sleep(0.25)
text = text + char
# プログレスバーの表示
# 75%|████████████████████████████████ | 3/4 [00:06<00:02, 2.01s/it]また、tqdm(range(i))はtrange(i)で代用できます。
from tqdm import trange
for i in trange(50):
sleep(0.01)
# 以下と同じ
for i in tqdm(range(50)):
sleep(0.01)表示をカスタマイズ
以下の引数でプログレスバーの表示を変えることができます（以下の引数はすべてOptionalです）。
説明テキストの設定
プログレスバーの左端に説明テキストを表示できます。desc引数に文字列を指定することで設定できます。
for i in tqdm(range(100), desc="progress bar sample", ncols=100):
time.sleep(0.001)
# プログレスバーの表示
# progress bar sample: 100%|███████████████████████████████████████| 100/100 [00:00<00:00, 793.81it/s]単位の設定
ループの単位を変更できます。デフォルトはitですが、処理の内容に合わせてstepなど自由に指定できます。unit引数に希望の単位を文字列で指定します。
for i in tqdm(range(100), unit="step"):
time.sleep(0.001)
# 右端にstep/sが表示されている
# 100%|██████████████████████████████████████████████████████████| 100/100 [00:00<00:00, 788.01step/s]バーの幅設定
プログレスバーの全体的な幅を調整できます。デフォルトでは実行環境（ターミナルなど）の幅に合わせますが、ncols引数に整数値を指定して幅を固定できます。
for i in tqdm(range(100), ncols=50):
time.sleep(0.001)
# ncols=50の例
# 100%|██████████| 100/100 [00:00<00:00, 792.32it/s]for i in tqdm(range(100), ncols=100):
time.sleep(0.001)
# ncols=100の例
# 100%|████████████████████████████████████████████████████████████| 100/100 [00:00<00:00, 793.27it/s]応用例
ネストされたループ
tqdmはネストをサポートしているため、複数のループを同時に可視化することができます。leave=Falseを指定すると、内側のループ完了後にバーの表示を消去します。
for outer in tqdm(range(3), desc="Outer loop"):
for inner in tqdm(range(5), desc="Inner loop", leave=False):
time.sleep(0.2)pandasとの統合
データ処理ライブラリであるpandasと統合可能です。
import pandas as pd
from tqdm import tqdm
# tqdm.pandas()を呼び出して統合を有効化
tqdm.pandas(desc="Pandas progress")
# サンプルデータ作成
data = pd.DataFrame({"numbers": range(100)})
# DataFrame.applyで進行状況を可視化。
# ここでは、applyの代わりにprogress_applyが使えるようになっている。
data["squared"] = data["numbers"].progress_apply(lambda x: x ** 2)まとめ
tqdmはほんの数行のコードで使い始められるのに加え、きめ細やかなカスタマイズができる便利なライブラリです。本記事で紹介したように、tqdmには以下のような特徴があります：
- 簡単なループでの利用: tqdm(range(n))のようにラップするだけで進捗バーを表示
- カスタマイズ性: desc, unit, ncolsなどで自由に調整可能
- 応用力: ネストされたループやpandasとの統合も可能
大規模データの前処理やスクレイピングなど、pythonで長時間の処理を走らせる場面では、ぜひtqdmのプログレスバーを活用してみてください。視覚的な進捗表示によって、処理の状況が把握しやすくなり、開発効率も向上するでしょう。
