本文讲解为何自定义 print(..., end='\r') 进度条在 df.apply() 中会重复渲染多个条，以及如何使用 tqdm 实现稳定、高效、仅显示一个动态更新的进度条。
本文讲解为何自定义 print(..., end='\r') 进度条在 df.apply() 中会重复渲染多个条，以及如何使用 tqdm 实现稳定、高效、仅显示一个动态更新的进度条。
在 Jupyter Notebook 中为 pandas.DataFrame.apply() 添加进度反馈时，直接使用 print(..., end='\r') 实现的自定义进度条容易出现“多条叠加”问题——尤其当数据量增大（如 5000 行）时，控制台会不断刷新并残留多个旧进度条，而非覆盖更新为单一动态条。根本原因在于：df.apply() 在底层可能触发多次函数调用上下文切换、Jupyter 输出缓冲机制不兼容 \r 回车符的逐行覆盖行为，且 global 变量与并行/分块执行逻辑存在隐式冲突（即使默认是单线程，Pandas 内部仍可能重排或缓存输出）。
更可靠、专业的解决方案是采用专为交互环境优化的 tqdm 库：
✅ 推荐做法（Jupyter 专用）：
from tqdm.notebook import tqdm
import pandas as pd
# 启用 tqdm 对 pandas 的集成支持
tqdm.pandas(desc="Processing rows")
# 定义处理函数（无需手动维护计数器）
def myf(row):
row['1'] = 100
return row # 注意：apply 需要返回值以保留结果结构
# 使用 progress_apply 替代 apply —— 自动注入单条、可刷新、带描述的进度条
df = pd.DataFrame(index=range(0, 5000), columns=['1','2','3','4','5'])
df = df.progress_apply(myf, axis=1)
? 关键优势说明：
- tqdm.notebook 版本专为 Jupyter 的富输出协议设计，支持 HTML 渲染、平滑动画及自动清理旧输出；
- progress_apply() 是 tqdm 提供的封装方法，内部已处理迭代计数、刷新频率与输出同步，彻底规避 \r 兼容性问题；
- 不再需要 global 计数器、len(df) 手动传参或 math.ceil 等冗余逻辑，代码更简洁、线程安全、可维护性强；
- 支持 desc（描述）、unit（单位）、leave=False（完成后是否保留条）等参数，灵活适配各类场景。
⚠️ 注意事项：
- 若未安装 tqdm，请先运行 pip install tqdm；
- 切勿在 progress_apply 中混用 print() 或其他输出语句，以免干扰进度条渲染；
- progress_apply 返回的是新 DataFrame（非原地修改），如需就地更新，请显式赋值（如示例所示）；
- 对于超大数据集，考虑改用 dask 或 modin 加速，但进度条仍可无缝集成。
综上，放弃手写 \r 进度条，拥抱 tqdm.notebook 是 Jupyter + Pandas 工作流中的最佳实践——它让进度可视化真正“可靠、轻量、专业”。
