写 Python 程序时，你有没有遇到过这种场景：
代码已经运行了 5 分钟，屏幕却一点反应都没有。你不知道它是在认真工作，还是已经卡死。你也不知道还要等 10 秒、10 分钟，还是干脆等不到结果。这时候，一个看似不起眼的小工具就很有用了：tqdm。
tqdm 是 Python 里非常常用的进度条库。它的作用很简单：让程序在处理循环任务时，把“当前进度、处理速度、剩余时间”等信息显示出来。
一句话概括就是：
tqdm 让 Python 程序不再“闷头干活”，而是边干边告诉你进度。
一、为什么需要 tqdm？
很多 Python 程序都会涉及循环，比如：
读取一批文件；
处理几万条数据；
下载多个资源；
训练机器学习模型；
爬取网页内容；
批量压缩图片；
遍历一个很大的列表。
这些任务往往不是一秒钟就结束的。如果没有进度提示，用户只能盯着空白的终端窗口发呆。
比如下面这段代码：
import timefor i in range(100): time.sleep(0.1)
它会运行一段时间，但你看不到任何反馈。
加上 tqdm 之后：
from tqdm import tqdm
import time
for i in tqdm(range(100)):
time.sleep(0.1)
运行时，终端里就会出现类似这样的进度条：
76%|███████████████████████ | 76/100 [00:07<00:02, 9.87it/s]
这一行信息看起来不复杂，但很有用。它告诉你当前完成了多少、总量是多少、已经运行多久、预计还剩多久，以及每秒大约能处理多少次。
二、tqdm 最核心的用法：包一层就行
tqdm 的设计非常轻量，最常见的用法就是：
from tqdm import tqdm
for item in tqdm(iterable):
do_something(item)
也就是说，原来你写：
for item in data:
process(item)
现在只需要改成：
for item in tqdm(data):
process(item)
它不改变原来的循环逻辑，只是在外面加了一层“进度显示”。
这也是 tqdm 受欢迎的重要原因：它很少打扰原有代码。
三、安装方式
安装也很简单：
如果你使用的是 Anaconda，也可以用：
安装完成后，就可以在 Python 脚本中导入使用：
四、几个常见使用场景
1. 普通循环
from tqdm import tqdm
import time
for i in tqdm(range(1000)):
time.sleep(0.01)
适合用来观察长循环的执行进度。
2. 遍历列表
from tqdm import tqdm
names = ["Alice", "Bob", "Cindy", "David"]
for name in tqdm(names):
print(name)
只要对象可以被循环遍历，通常就可以交给 tqdm。
3. 给进度条加说明文字
from tqdm import tqdm
import time
for i in tqdm(range(100), desc="正在处理数据"):
time.sleep(0.05)
运行时，进度条前面会显示“正在处理数据”，适合让输出更清晰。
4. 在 pandas 中使用
处理 DataFrame 时，也可以让 apply 显示进度。
import pandas as pd
from tqdm import tqdm
tqdm.pandas()
df["result"] = df["text"].progress_apply(lambda x: len(x))
平时用 df["text"].apply(...) 时，数据量一大就容易不知道处理到哪了。换成 progress_apply 后，就可以看到进度条。
5. 在 Jupyter Notebook 中使用
如果你在 Jupyter Notebook 里写代码，可以使用：
from tqdm.notebook import tqdm
for i in tqdm(range(100)):
pass
这样显示效果会更适合 Notebook 页面。
五、tqdm 显示的信息是什么意思？
一条常见的 tqdm 进度条可能长这样：
100%|████████████████████████████| 1000/1000 [00:10<00:00, 98.7it/s]
可以拆开理解：
100%：任务完成百分比。
1000/1000：当前完成数量 / 总数量。
00:10：已经运行的时间。
00:00：预计剩余时间。
98.7it/s：每秒处理约 98.7 次迭代。
这里的 it/s 是 iterations per second，也就是“每秒迭代次数”。
对数据处理、爬虫、模型训练这类任务来说，这些信息非常实用。你不仅知道程序还活着，还能粗略判断它的运行效率。
六、什么时候适合用 tqdm？
tqdm 特别适合下面几类任务：
第一，循环次数比较多。
比如几千次、几万次、几十万次。
第二，每次循环耗时相对明显。
比如读取文件、请求网络、处理图片、计算特征。
第三，你希望知道任务剩余时间。
比如跑批处理脚本、模型训练脚本、数据清洗脚本。
第四，你希望提升脚本的可读性和可观察性。
尤其是别人运行你的程序时，进度条比一片空白友好得多。
不过，如果循环很短，比如只运行几十毫秒，就没必要加 tqdm。进度条本身也会带来极小的额外开销，虽然通常可以忽略，但在极端高频、极短耗时的循环里，没必要强行使用。
七、一个小例子：批量处理文件
假设我们要处理一个文件夹下的所有 .txt 文件：
from pathlib import Path
from tqdm import tqdm
folder = Path("./data")
files = list(folder.glob("*.txt"))
for file in tqdm(files, desc="处理文本文件"):
text = file.read_text(encoding="utf-8")
# 在这里处理 text
如果文件数量很多，进度条就能清楚显示当前处理到了第几个文件。
这类场景在实际工作中非常常见：数据清洗、日志分析、文本处理、图片处理，基本都能用上。
八、tqdm 的价值不只是“好看”
很多人第一次见到 tqdm，会觉得它只是让终端多了一个进度条，好像只是视觉增强。
其实它解决的是一个更实际的问题：程序可观察性。
所谓可观察性，就是程序运行时，你能不能知道它在做什么、做到哪一步、速度是否正常、是否可能卡住。
没有 tqdm 时，长任务就像一个黑盒。
加上 tqdm 后，程序至少会告诉你：我还在跑，已经跑到这里了。
这对开发者调试代码、估算时间、发现性能瓶颈都很有帮助。
九、总结
tqdm 是一个小而实用的 Python 工具。
它不复杂，不需要大幅修改代码，也不要求你学习一套新的编程模式。很多时候，只要给原来的循环外面包一层 tqdm()，就能立刻获得一个清晰的进度条。
对于经常做数据处理、爬虫、批量文件操作、机器学习实验的 Python 用户来说，tqdm 几乎属于“装了不一定每天想起，但用到时非常顺手”的工具。下次当你的 Python 程序又开始沉默运行时，不妨给它加一行 tqdm。让程序跑得慢一点不可怕，可怕的是你不知道它到底跑到哪了。
