tqdm介绍

tqdm 是 Python 中一款轻量级的进度条库，能实时显示循环、迭代或任务的执行进度，让代码运行状态更直观。

这个工具的核心价值在于 “可视化等待过程”，尤其适合处理数据加载、文件处理、模型训练等耗时任务，避免因看不到进度而产生 “程序是否卡住” 的疑惑。

特点

• 使用极简： 只需用 tqdm() 包裹可迭代对象（如列表、range），无需额外复杂配置。
• 轻量无依赖： 安装和运行无需依赖其他大型库，对项目体积影响小。
• 高度可定制： 支持自定义进度条样式、显示信息（如剩余时间、速度）、更新频率等。

下载方式与其他python包相同

pip install tqdm

tqdm创建

tqdm的原理就是在控制台当中创建了一个tqdm实例，常见的更新tqdm实例的方法主要分两种：

1. 随循环增加tqdm的次数
2. 显示调用实例并且手动更新

tqdm示例

from tqdm import tqdm
import time

# 模拟深度学习训练循环
epochs = 10
for epoch in tqdm(range(epochs), desc="Training Epoch"):
    # 模拟一个epoch的训练过程
    time.sleep(2)
    # 训练代码...

tqdm在实际使用当中十分方便，这里能很明显的发现如果希望在开发环境当中加入进度条，只需要修改for循环就能实现

另外，对于经常使用 range 的情况，tqdm 提供了trange快捷方式，功能与 tqdm (range (…)) 完全相同：

from tqdm import trange

for epoch in trange(epochs, desc="Training Epoch"):
    time.sleep(2)
    # 训练代码...

最终得到的进度条如下：

Training Epoch: 100%|██████████| 10/10 [00:20<00:00,  2.01s/it]

理解进度条上各个参数的含义对科研人员至关重要。典型的进度条格式如下：
[描述信息] [百分比] [进度条] [当前进度/总进度] [已用时间<剩余时间, 速度][后缀信息]（后缀信息可能为null）

具体参数说明：

• 百分比：已完成任务的百分比（如 76%）
• 进度条：可视化的进度显示（如███████████████████████████）
• 当前进度 / 总进度：已完成的迭代数与总迭代数（如 7568/10000）
• 已用时间 < 剩余时间：从开始到现在的时间和预计剩余时间（如 00:33<00:10）
• 速度：每秒处理的项目数的开销极低，仅约 60 纳秒 / 次迭代（使用 tqdm.gui 时为 80 纳秒），相比之下，老牌的 ProgressBar 库开销高达 800 纳秒 / 次迭代。这种高效性使其特别适合长时间运行的深度学习训练任务。

手动更新进度条

from tqdm import tqdm
import time

# 手动控制进度条
total_batches = 100
'''创建了一个可手动控制的进度条实例'''
with tqdm(total=total_batches, desc="Manual Update") as pbar: 
    for i in range(10):  #10*10 = 100————适配了total_batches
        # 模拟处理10个批次
        time.sleep(0.2)
        # 手动更新进度（每次增加10个批次）
        pbar.update(10)  # pbar.update(10) 每次手动增加10个单位的进度
 

在这段代码中，我们首先创建了可以手动控制进度的实例，然后通过update让其在控制台当中不断更新，这样的控制方法更接近其本质——只是画出一个大致的进度而无法反应每一个进程实际所需要的时间

值得注意的是，我们在这里是使用了with方法去创建了一个实例，如果选择直接创建的话，则有必要在后续close该进程：

pbar = tqdm(total=100)
try:
    for i in range(10):
        pbar.update(10)
finally:
    pbar.close()

添加描述和后缀信息

在深度学习训练中，实时显示训练指标（如损失值、准确率）对监控训练过程至关重要。tqdm 提供了set_description和set_postfix方法来动态更新进度条的描述信息：

from tqdm import tqdm
import time

# 手动控制进度条
total_batches = 100
'''创建了一个可手动控制的进度条实例'''
with tqdm(total=total_batches, desc="Manual Update") as pbar: 
    for i in range(10):
        # 模拟处理10个批次
        time.sleep(0.2)
        # 手动更新进度（每次增加10个批次）
        pbar.update(10)  # pbar.update(10) 每次手动增加10个单位的进度，而不是默认的每次增加1
        # 可以在更新时添加动态信息
        pbar.set_postfix(后缀信息 = " 可以这样添加后缀信息 ")

自定义进度条样式

tqdm 允许通过bar_format参数完全自定义进度条的显示格式。这对于需要特定显示格式的科研场景特别有用

from tqdm import tqdm
import time
import random

def demo_custom_progress_bars():
    # 1. 基础自定义
    print("示例 1: 基础自定义")
    for i in tqdm(range(100), 
                  desc="基础进度",
                  bar_format="{l_bar}{bar:40}{r_bar}",
                  ascii="->="):
        time.sleep(0.01)
    
    # 2. 显示详细信息
    print("\n示例 2: 显示详细信息")
    for i in tqdm(range(100), 
                  desc="详细进度",
                  bar_format="{desc}: {percentage:3.0f}%|{bar}| {n_fmt}/{total_fmt} "
                             "[耗时:{elapsed}, 剩余:{remaining}, 速度:{rate_fmt}]"):
        time.sleep(0.02)
    
    # 3. 自定义动态信息
    print("\n示例 4: 自定义动态信息")
    pbar = tqdm(range(100), desc="动态信息")
    for i in pbar:
        # 在进度条中添加动态变化的信息
        current_speed = random.uniform(0.5, 2.0)
        pbar.set_postfix(speed=f"{current_speed:.2f}it/s", 
                         status="处理中" if i < 70 else "即将完成")
        time.sleep(0.02)
    pbar.close()

if __name__ == "__main__":
    demo_custom_progress_bars()

tqdm 常用参数速查表

参数	作用说明	示例代码
desc	进度条前添加描述文字	tqdm(range(100), desc="下载文件")
total	手动指定总步数（非迭代对象时必用）	pbar = tqdm(total=50); pbar.update(1)
ncols	控制进度条总宽度（字符数）	tqdm(range(100), ncols=100)
leave	任务结束后是否保留进度条（默认 True）	tqdm(range(100), leave=False)
unit	显示单位（如 “B” 表示字节，“it” 表示迭代）	tqdm(range(100), unit="B")
unit_scale	自动缩放单位（如 K、M，配合 unit 使用）	tqdm(range(1024), unit="B", unit_scale=True)
colour	设置进度条颜色（支持 “red”、“green” 等）	tqdm(range(100), colour="green")
smoothing	平滑显示速度（0-1，0 表示实时）	tqdm(range(100), smoothing=0.5)