Python rich-tqdm 完整使用文档richtqdm/rich_tqdm一、包基础概述1. 核心定位rich-tqdm是融合rich终端美化库与tqdm进度条库的增强进度条工具替代原生tqdm提供彩色、多组件、分层、表格样式终端进度条支持日志、进度、数值、时间、速度、文件大小一体化渲染解决原生tqdm单调黑白、自定义样式繁琐、多任务进度展示混乱问题。包名两种写法rich_tqdm导入规范、richtqdm别名官方仓库包名rich-tqdmpip安装用横杠。2. 核心功能彩色美化进度条自定义前景/背景色、渐变进度条、边框样式多维度进度信息完成百分比、已耗时、剩余预估、迭代速度、总量/当前值、文件单位自动转换(B/KB/MB/GB)多任务并行进度同时展示多个循环进度条分层不重叠内置rich组件内嵌文本日志、表格、状态标签、Spinner加载动画兼容tqdm全部语法无缝替换原有tqdm()代码改动极小动态更新数值支持实时修改进度描述、自定义指标损失、准确率、内存占用自动适配终端自适应终端宽度窄终端自动压缩组件无排版错乱静默模式/日志输出支持将进度写入文件不占用终端二、安装方式1. 标准pip安装# 稳定版推荐pipinstallrich-tqdm# 国内加速pipinstallrich-tqdm-ihttps://pypi.tuna.tsinghua.edu.cn/simple# 升级版本pipinstall--upgraderich-tqdm2. 源码安装最新开发版gitclone https://github.com/textualize/rich-tqdm.gitcdrich-tqdm pipinstall.3. 依赖说明自动安装依赖rich12.0.0、tqdm4.60.0、typing-extensions无需手动安装rich。三、导入与基础语法1. 两种导入方式# 方式1兼容tqdm原生写法最常用fromrich_tqdmimporttqdm# 方式2单独导入进度条对象、进度管理器fromrich_tqdmimportRichTqdm,track2. 基础语法结构语法1遍历迭代器和tqdm完全一致foritemintqdm(iterable,关键字参数):# 业务逻辑pass语法2手动步进手动控制进度无迭代对象pbartqdm(total100,desc任务)foriinrange(100):# 业务逻辑pbar.update(1)# 步进1pbar.close()语法3track快捷封装简化文件/批量任务fromrich_tqdmimporttrackforfileintrack(file_list,desc读取文件):pass四、全部核心参数详解一基础迭代参数兼容原生tqdm参数类型作用默认值iterable可迭代对象循环对象(list/range/生成器)Nonetotalint任务总数量未知时设None自动读取len(iterable)descstr进度条左侧描述文字“”leavebool循环结束后是否保留进度条Truedisablebool是否关闭进度条脚本静默运行Falseunitstr迭代单位如it、file、MB“it”unit_scalebool自动缩放单位(1000/1024)Falseminintervalfloat最小刷新间隔(秒)减少刷屏0.1smoothingfloat速度平滑系数(0~1)平滑预估剩余时间0.3二rich独有美化参数核心特色参数类型作用示例值bar_stylestr进度条填充颜色样式green bold、#00ccffcomplete_stylestr已完成区块样式rgb(0,255,0)finished_stylestr全部完成后整体样式bold redpulsebool完成后脉冲闪烁动画Truespinnerstr前置加载动画rich内置spinnerdots、lineshow_speedbool是否展示每秒迭代速度Trueshow_percentagebool是否显示百分比Trueshow_timebool是否显示已耗时/剩余时间Trueshow_totalbool是否显示当前/总量数值Truewidthint固定进度条宽度None自适应终端Nonetransientbool任务结束自动清除进度条Falselog_colorstr内嵌日志文字颜色gray三自定义动态指标参数postfix字典/字符串右侧附加自定义指标动态更新pbar.set_postfix(loss0.23,acc0.95,memory1.2GB)postfix_style自定义指标文字颜色五、8个完整可运行实战案例案例1基础循环美化进度条最简入门场景普通数值循环彩色绿色进度条fromrich_tqdmimporttqdmimporttime# range迭代设置描述、单位、绿色进度条foriintqdm(range(50),desc数字计算,unit次,bar_stylegreen bold):time.sleep(0.05)效果绿色渐变进度条显示耗时、速度、49/50、98%案例2手动update步进动态更新后置指标场景机器学习训练实时更新损失、准确率fromrich_tqdmimporttqdmimporttime# 手动创建进度条总批次200pbartqdm(total200,desc模型训练,bar_stylecyan)forepochinrange(200):# 模拟训练计算loss0.5-epoch*0.002accepoch/200time.sleep(0.02)# 动态更新右侧指标pbar.set_postfix(lossf{loss:.3f},accf{acc:.3f})pbar.update(1)pbar.close()案例3文件批量处理自动字节单位转换场景遍历文件列表统计文件大小单位自动MB/GBfromrich_tqdmimporttrackimportos file_paths[f./temp_{i}.txtforiinrange(30)]# unit_scaleTrue 自动换算文件大小单位forfileintrack(file_paths,desc读取文件,unitB,unit_scaleTrue,bar_styleblue):# 模拟读取文件占用字节file_size1024*500time.sleep(0.03)案例4多任务并行多层进度条嵌套循环场景双层循环外层大任务、内层子任务分层进度展示fromrich_tqdmimporttqdmimporttime# 外层循环fortaskintqdm(range(5),desc总任务组,bar_styleorange):# 内层子循环forsubtaskintqdm(range(20),descf子任务-{task},leaveFalse,bar_stylelight_blue):time.sleep(0.04)leaveFalse内层完成自动销毁不堆积多条进度条案例5关闭进度条静默模式脚本后台运行场景定时任务/服务器后台执行不需要终端进度输出fromrich_tqdmimporttqdmimporttime# disableTrue 完全隐藏进度条仅执行逻辑datalist(range(100))fordintqdm(data,desc后台数据清洗,disableTrue):time.sleep(0.01)案例6transient临时进度条完成自动清除场景一次性短时任务结束后终端不留进度痕迹fromrich_tqdmimporttqdmimporttime# transientTrue 运行结束自动删除进度条foriintqdm(range(30),desc临时加载,transientTrue,bar_stylemagenta):time.sleep(0.06)案例7自定义渐变颜色Spinner加载动画场景数据爬虫前置动态转圈动画渐变色进度条fromrich_tqdmimporttqdmimporttime# spinner指定加载动画rgb自定义彩色进度pbartqdm(range(80),desc网页爬虫,spinnerdots2,bar_style#ff6600 bold,finished_style#00ff00 bold)forpageinpbar:time.sleep(0.05)# 动态描述更新pbar.set_description(f爬取第{page}页)案例8超大循环低刷屏平滑速度预估场景百万级数据迭代降低刷新频率避免终端卡顿fromrich_tqdmimporttqdmimporttime# mininterval最小刷新间隔0.5秒smoothing平滑速度big_datarange(10000)foritemintqdm(big_data,desc百万数据处理,mininterval0.5,smoothing0.1,bar_stylegray):ifitem%1000:time.sleep(0.001)六、常见报错、错误原因与解决方案错误1ModuleNotFoundError: No module named ‘rich_tqdm’原因包未安装或安装时输错包名不能写richtqdmpip安装必须rich-tqdm解决pipinstallrich-tqdm错误2TypeError: tqdm() got an unexpected keyword argument ‘bar_style’原因1导入了原生tqdm而非rich_tqdm原生tqdm无美化参数原因2rich-tqdm版本过低旧版本不支持样式参数解决# 修正导入fromrich_tqdmimporttqdm# 升级包pip install--upgrade rich-tqdm错误3进度条疯狂刷屏、终端卡顿原因循环逻辑极快默认0.1秒刷新间隔输出过多解决增大mininterval参数降低刷新频率tqdm(range(100000),mininterval0.5)错误4嵌套循环内层进度条残留终端排版混乱原因内层循环leaveTrue默认子任务完成不销毁解决内层设置leaveFalsetqdm(range(20),leaveFalse)错误5Windows cmd终端颜色不显示只有黑白文字原因cmd不支持ANSI彩色转义码解决使用Windows Terminal / PowerShell脚本顶部启用颜色importos os.system(color)错误6total不指定进度条显示?/??未知总量原因迭代对象无__len__生成器、数据流无法自动计算total解决手动传入total参数gen(iforiinrange(100))tqdm(gen,total100)错误7set_postfix传参时报错TypeError原因数值未格式化传入浮点数/int直接渲染出错解决统一转为字符串格式化pbar.set_postfix(lossf{loss:.4f})错误8多线程运行进度条重叠错乱原因rich-tqdm非线程安全多线程共用终端缓冲区解决单线程使用进度条多线程时disableTrue关闭进度改用日志文件输出。七、使用注意事项与最佳实践1. 环境适配Linux/macOS终端完美支持全部颜色动画Windows CMD存在色彩兼容问题推荐Windows Terminal。服务器无交互式终端crontab后台脚本必须设置disableTrue否则会输出大量乱码。2. 性能优化高速循环务必设置mininterval 0.2减少IO刷屏消耗CPU百万级迭代避免频繁调用set_postfix可每100次迭代更新一次指标不需要彩色时直接用原生tqdmrich-tqdm有轻微性能损耗。3. 代码兼容规范想要无缝迁移原有tqdm代码仅修改导入行即可其余参数完全通用生产环境脚本建议增加开关控制进度条verboseFalse# 生产环境关闭进度pbartqdm(data,disablenotverbose)4. 嵌套进度规范多层循环统一内层leaveFalse外层保留leaveTrue保证终端整洁不建议超过3层嵌套分层过多可读性下降。5. 颜色规范颜色支持三种格式英文颜色名(green/red)、RGB字符串rgb(255,0,0)、十六进制#ff0000可叠加样式修饰bold加粗、italic斜体、underline下划线。6. 禁止场景多进程/多线程共享同一个tqdm对象会造成渲染崩溃日志文件输出重定向python run.py log.txt时关闭进度条ANSI色彩码会污染日志文本Jupyter Notebook中部分旧内核Spinner动画失效改用spinnernone。7. 内存释放手动创建pbar tqdm()对象时循环结束必须执行pbar.close()否则终端光标会异常偏移for循环自动迭代形式无需手动关闭。《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章前6章涵盖深度学习基础包括张量运算、神经网络原理、数据预处理及卷积神经网络等后5章进阶探讨图像、文本、音频建模技术并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法每章附有动手练习题帮助读者巩固实战能力。内容兼顾数学原理与工程实现适配PyTorch框架最新技术发展趋势。