tqdm 是一个 Python 库，用于在长时间运行的任务中显示进度条。tqdm.auto 是 tqdm 的一个版本，能够自动适配输出环境（如 Jupyter Notebook、命令行等），以确保进度条在各种环境下显示正确。下面是 tqdm.auto 的详细用法介绍及示例。
1.tqdm.auto 的基本用法
-
基础用法
tqdm可以很方便地用于显示循环的进度条。from tqdm.auto import tqdm import timefor i in tqdm(range(100)):time.sleep(0.1) # 模拟一个耗时操作上面代码会显示一个进度条，每次循环迭代时进度条都会更新，直到任务完成。
-
使用在函数中
你可以将tqdm应用于任何可迭代对象，包括列表、生成器等。from tqdm.auto import tqdm import timedef process_data(data):for item in tqdm(data):time.sleep(0.1) # 模拟数据处理 data = range(50) process_data(data)
-
自定义进度条参数
tqdm允许定制进度条的显示格式，包括进度条的描述、步长、刷新率等。from tqdm.auto import tqdm import timefor i in tqdm(range(100), desc="Processing", unit="iter", ncols=100, colour="green"):time.sleep(0.05) # 模拟一个耗时操作
参数解释：
desc: 进度条的描述文字，默认不显示。unit: 步长单位，默认是 ‘it’。ncols: 进度条的宽度，单位为字符。colour: 进度条的颜色，默认颜色由环境决定。
- 嵌套进度条
当处理嵌套循环时，可以使用多层tqdm进度条。
from tqdm.auto import tqdm
import timefor i in tqdm(range(3), desc="Outer Loop", colour="green"):for j in tqdm(range(100), desc="Inner Loop", leave=False, colour="blue"):time.sleep(0.01)
外层循环会显示为一个外部进度条，而内层循环的进度条会显示为内部的子进度条。
- 手动更新进度条
对于不使用循环的情况，也可以手动更新进度条。
from tqdm.auto import tqdm
import timeprogress_bar = tqdm(total=100)
for i in range(10):time.sleep(0.5) progress_bar.update(10) # 以10%的速度更新进度条
progress_bar.close()
total: 进度条的总数目。update(n): 手动增加进度条的进度，n是步长。
- 结合 Pandas
tqdm可以结合 Pandas 显示进度条，例如在apply或groupby操作中。
import pandas as pd
from tqdm.auto import tqdmtqdm.pandas() # 启用 tqdm for pandasdf = pd.DataFrame({'a': range(1000)})
df['b'] = df['a'].progress_apply(lambda x: x**2)
- 结合文件下载
tqdm也可以用于显示文件下载进度。
import requests
from tqdm.auto import tqdmurl = "https://example.com/largefile.zip"
response = requests.get(url, stream=True)
total_size = int(response.headers.get('content-length', 0))with open("largefile.zip", 'wb') as file, tqdm(desc="Downloading", total=total_size, unit='B', unit_scale=True, unit_divisor=1024
) as bar:for data in response.iter_content(chunk_size=1024):file.write(data)bar.update(len(data))
2. tqdm 常见入参
-
iterable: 任何可迭代对象，如
range()、列表、生成器等。- 类型:
iterable - 默认值:
None - 说明: 表示需要显示进度条的对象。
- 类型:
-
desc: 进度条左侧的描述文字。
- 类型:
str - 默认值:
None - 说明: 为进度条加上说明文本，可以用于描述当前任务。
tqdm(range(100), desc="Loading") - 类型:
-
total: 迭代的总步数。
- 类型:
int - 默认值:
None - 说明: 如果没有提供可迭代对象（即手动更新进度），需要指定总步数。
tqdm(total=100) - 类型:
-
leave: 是否在任务完成后保留进度条。
- 类型:
bool - 默认值:
True - 说明:
True表示任务完成后进度条保持在屏幕上；False表示任务完成后清除进度条。
tqdm(range(100), leave=False) - 类型:
-
ncols: 进度条的宽度（字符数）。
- 类型:
int - 默认值:
None（自动调整宽度） - 说明: 控制进度条在屏幕上显示的宽度。
tqdm(range(100), ncols=80) - 类型:
-
mininterval: 最小刷新间隔时间（秒）。
- 类型:
float - 默认值:
0.1 - 说明: 控制进度条刷新的最小时间间隔，避免过于频繁刷新，减少系统开销。
tqdm(range(100), mininterval=0.5) - 类型:
-
maxinterval: 最大刷新间隔时间（秒）。
- 类型:
float - 默认值:
10 - 说明: 设置进度条的最大刷新间隔时间。如果任务较长，可以设定一个上限，以确保定期刷新。
tqdm(range(100), maxinterval=5) - 类型:
-
miniters: 最小更新步数。
- 类型:
intorfloat - 默认值:
1 - 说明: 控制进度条更新的最小步长。例如，每 10 步才刷新一次。
tqdm(range(100), miniters=10) - 类型:
-
ascii: 使用 ASCII 字符显示进度条（适用于不支持 Unicode 的终端）。
- 类型:
boolorstr - 默认值:
False - 说明: 使用
True时，会用 ASCII 字符显示进度条。你也可以传入自定义的字符序列。
tqdm(range(100), ascii=True) - 类型:
-
disable: 禁用进度条。
- 类型:
bool - 默认值:
False - 说明: 设置为
True时，禁用进度条（例如用于不需要显示进度条的环境中）。
tqdm(range(100), disable=True) - 类型:
-
unit: 进度条步长单位。
- 类型:
str - 默认值:
'it' - 说明: 用于指示进度条的单位，例如字节、行、项等。
tqdm(range(100), unit="B") - 类型:
-
unit_scale: 是否自动缩放单位。
- 类型:
boolorintorfloat - 默认值:
False - 说明: 设置为
True时，自动调整单位，如 1024 -> 1K。可以手动指定缩放倍数。
tqdm(range(10000), unit_scale=True) - 类型:
-
unit_divisor: 单位缩放的基数。
- 类型:
int - 默认值:
1000 - 说明: 控制单位缩放时的除数，常用于字节单位显示（如
1024）。
tqdm(range(10000), unit="B", unit_scale=True, unit_divisor=1024) - 类型:
-
dynamic_ncols: 动态调整进度条宽度。
- 类型:
bool - 默认值:
True - 说明: 进度条会根据终端窗口宽度动态调整长度。
tqdm(range(100), dynamic_ncols=True) - 类型:
-
smoothing: 平滑速度的系数。
- 类型:
float - 默认值:
0.3 - 说明: 用于计算平均速度的平滑因子，数值越小，更新越灵敏。
tqdm(range(100), smoothing=0.1) - 类型:
-
colour: 设置进度条颜色。
- 类型:
str - 默认值:
None - 说明: 可以设置进度条的颜色，例如
'green'。
tqdm(range(100), colour="green") - 类型:
示例代码
from tqdm.auto import tqdm
import timefor i in tqdm(range(100), desc="Processing", total=100, unit="iter", ncols=100, leave=False, mininterval=0.5, ascii=True, colour="blue"):time.sleep(0.05)
通过这些参数，tqdm 可以非常灵活地定制进度条的显示方式。
