tqdm

tqdm - インテリジェントなプログレスバー

tqdmは、Pythonの長時間実行されるループを監視する標準ツールです。オーバーヘッドはごくわずか（1イテレーションあたり約60ns）で、コンソール、Jupyterノートブック、さらにはGUIなど、あらゆる環境で動作します。

使用する場面

• 長時間実行されるループ（シミュレーション、データ処理、MLのトレーニング）の監視。
• ファイルのダウンロードやI/O操作の進捗状況の追跡。
• コマンドラインツールでの視覚的なフィードバックの提供。
• pandasの操作（progress_apply）への進捗状況の追跡の統合。
• concurrent.futuresやmultiprocessingでの並列タスクの監視。
• 階層的なタスク（エポックやバッチなど）のための、入れ子になったプログレスバーの作成。

リファレンスドキュメント

公式ドキュメント: https://tqdm.github.io/
GitHub: https://github.com/tqdm/tqdm
検索パターン: from tqdm import tqdm、tqdm.pandas()、tqdm.notebook、tqdm.contrib

基本原則

イテラブルをラップする

tqdmを使う最も簡単な方法は、任意のイテラブルをラップすることです：for item in tqdm(iterable):。長さを自動的に計算し、残り時間を推定します。

低オーバーヘッド

tqdmは非常に高速に動作するように記述されています。実際の計算が遅くならないよう、表示を更新する回数を制限するスマートなアルゴリズムを使用します。

統合

tqdmには、さまざまな環境（Jupyter、Keras、Pandas、Slack／Telegramの通知）向けの専用モジュールがあります。

クイックリファレンス

インストール

pip install tqdm

標準的なインポート

from tqdm import tqdm
import time

# For Jupyter Notebooks specifically:
# from tqdm.notebook import tqdm

基本パターン - ループの進捗状況を自動追跡

import time
from tqdm import tqdm

# Just wrap the range or list
for i in tqdm(range(1000)):
    time.sleep(0.01) # Simulate work

重要なルール

✅ 推奨事項

• descを使用する - バーに説明を追加して、どの処理が実行中かを正確に把握できるようにします（tqdm(range(10), desc="Processing")）。
• 入れ子になったループではleave=Falseを使用する - 内側のバーが完了した後に消去され、コンソールが煩雑になるのを防ぎます。
• ノートブック版を使用する - Jupyterでは、見やすいHTMLのバーを表示するためにfrom tqdm.notebook import tqdmを使用します。
• totalを手動で設定する - イテレーターに__len__がない場合は、totalパラメーターを手動で指定します。
• Pandasと統合する - tqdm.pandas()を使用して、.progress_apply()の進捗状況を確認します。
• 手動のバーを閉じる - 手動のpbar = tqdm(...)方式を使う場合は、必ずwith文を使うか、pbar.close()を呼び出します。

❌ 非推奨事項

• 更新頻度を上げすぎない - タイトなループ内で手動更新するのは避けます（例：毎秒数百万回の更新）。イテラブルをラップすれば、tqdmが自動的に処理します。
• tqdmの実行中にコンソールへ出力しない - 標準のprint()を使うとバーが崩れます。代わりにtqdm.write("message")を使用します。
• オーバーヘッドを無視しない - 小さいとはいえ、ループ本体の処理時間が1マイクロ秒未満の場合は、オーバーヘッドが問題になります。その場合はバッチ単位で処理します。
• ascii=Trueを忘れない - Unicodeに対応していない古いターミナルやWindows CMDを使用する場合は、文字化けを防ぐためにascii=Trueを指定します。

アンチパターン（絶対に避けること）

from tqdm import tqdm
import time

# ❌ BAD: Mixing print() and tqdm (Corrupts the bar)
for i in tqdm(range(5)):
    print(f"Doing step {i}") # Bar jumps to next line
    time.sleep(0.1)

# ✅ GOOD: Use tqdm.write()
for i in tqdm(range(5)):
    tqdm.write(f"Doing step {i}") # Bar stays at the bottom
    time.sleep(0.1)

# ❌ BAD: Manual update without closing (Potential memory leak/UI hang)
pbar = tqdm(total=100)
for i in range(100):
    pbar.update(1)
# Missing pbar.close()!

# ✅ GOOD: Use context manager
with tqdm(total=100) as pbar:
    for i in range(100):
        pbar.update(1)

# ❌ BAD: Wrapping an iterator with no length without 'total'
# tqdm(my_generator) # Shows count but no progress bar/ETA

高度な使い方とカスタマイズ

説明と統計情報

pbar = tqdm(range(100))
for i in pbar:
    # Update description dynamically
    pbar.set_description(f"Processing Step {i}")
    
    # Add custom stats (e.g., loss in ML)
    pbar.set_postfix(loss=0.5/(i+1), accuracy=i/100)
    time.sleep(0.05)

手動制御（イテラブルでない処理向け）

# Useful for tracking bytes in file I/O or API calls
with tqdm(total=1024, unit='B', unit_scale=True, desc="Downloading") as pbar:
    # Simulate chunked download
    for chunk_size in [256, 128, 512, 128]:
        time.sleep(0.5)
        pbar.update(chunk_size)

エコシステムとの統合

Pandasとの統合

import pandas as pd
from tqdm import tqdm

# Initialize tqdm for pandas
tqdm.pandas(desc="Cleaning Data")

df = pd.DataFrame({'val': range(10000)})

# Use progress_apply instead of apply
result = df['val'].progress_apply(lambda x: x**2)

入れ子になったプログレスバー

# Perfect for Epochs vs Batches in deep learning
for epoch in tqdm(range(3), desc="Epochs"):
    for batch in tqdm(range(10), desc="Batches", leave=False):
        time.sleep(0.05)

並列処理（concurrent.futures）

from concurrent.futures import ThreadPoolExecutor
from tqdm import tqdm

def work(n):
    time.sleep(0.1)
    return n * 2

data = range(50)
with ThreadPoolExecutor() as executor:
    # Use tqdm to monitor map results
    results = list(tqdm(executor.map(work, data), total=len(data)))

実践的なワークフロー

1. 進捗状況を表示する大容量ファイルリーダー

import os

def read_large_file(filepath):
    """Read a file while showing a progress bar based on bytes."""
    file_size = os.path.getsize(filepath)
    with tqdm(total=file_size, unit='B', unit_scale=True, unit_divisor=1024) as pbar:
        with open(filepath, 'rb') as f:
            for chunk in iter(lambda: f.read(4096), b''):
                # Process chunk
                pbar.update(len(chunk))

2. 科学シミュレーションスイート

def run_simulation_suite(configs):
    """Run multiple simulations and log failures."""
    results = []
    with tqdm(configs, desc="Suite") as pbar:
        for config in pbar:
            try:
                res = run_single_sim(config)
                results.append(res)
            except Exception as e:
                tqdm.write(f"Error in config {config}: {e}")
            pbar.set_postfix(success=len(results))
    return results

3. カスタムの後置情報を使ったトレーニングループ

def train_model(epochs, data_loader):
    pbar = tqdm(range(epochs), desc="Training")
    for epoch in pbar:
        loss = compute_loss() # dummy
        acc = compute_acc()   # dummy
        
        # Update the bar with current metrics
        pbar.set_postfix(loss=f"{loss:.4f}", acc=f"{acc:.2%}")

パフォーマンスの最適化

minintervalパラメーター

デフォルトでは、tqdmは0.1秒ごとに更新します。ターミナルの応答が遅い場合（SSH経由や旧式のGUIなど）は、minintervalを1.0または5.0に増やして、ネットワーク／I/Oのトラフィックを減らします。

for i in tqdm(range(1000000), mininterval=1.0):
    pass

本番環境でtqdmを無効にする

disable=Trueを設定すると、バーをグローバルに無効化できます（CI/CD環境や、対話操作のないログでの実行時など）。

import os
# Check for environment variable
is_ci = os.environ.get('CI') == 'true'
for i in tqdm(range(100), disable=is_ci):
    pass

よくある問題と解決策

「二重バー」の不具合

Jupyterでは、バーが正しく閉じられず、赤や緑のバーが積み重なることがあります。

# ✅ Solution: Always use a 'with' statement or try-finally
# Or clear all instances if stuck:
from tqdm import tqdm
tqdm._instances.clear()

WindowsでのUnicodeエラー

Windows CMD（Terminal以外）では、滑らかな進捗ブロックが正しく表示されないことがよくあります。

# ✅ Solution: Use ASCII characters only
for i in tqdm(range(100), ascii=True):
    pass

複数のバーの位置合わせ

バーが重なったり、位置が飛んだりする場合は、次のようにしてください。

# ✅ Solution: Specify the position explicitly
# Useful for manual multi-threading
pbar1 = tqdm(total=100, position=0)
pbar2 = tqdm(total=100, position=1)

tqdm は、スクリプトに少し追加するだけで、大きな心理的安心感をもたらします。コードの「鼓動」を伝え、時間のかかる科学計算のタスクがどのように進んでいるかを常に把握できるようにします。