Python tqdm 库使用详解

Python 的 tqdm 库是一个快速、扩展性强的进度条工具库，可用于在长循环中添加一个进度提示信息。用户只需封装任意的迭代器 如 tqdm(iterator)。这样，每次迭代时都会在终端上更新进度条信息。

它被广泛应用于数据处理与分析、机器学习、网络请求、批量任务与循环、并行与多线程应用等领域。

安装

pip install tqdm

基本用法

tqdm 最常用的场景是对可迭代对象（如列表或生成器）进行遍历。以下是一个简单的示例：

from tqdm import tqdm
import time

# 使用 tqdm 包装可迭代对象
for item in tqdm(range(100)):
    time.sleep(0.1)

在这个例子中，tqdm 自动检测迭代的总次数，并以进度条的形式显示进度、估计剩余时间和当前迭代速度。

除了基本进度条之外，tqdm 还提供了许多自定义选项，例如自定义描述文字、进度条长度、填充字符等。

参数

以下参数除 iterable 外均为可选项。

tqdm 类的 init 函数（标注了各参数的类型和默认值，后文不再赘述）：

def __init__(self,
             iterable: Iterable[_T],
             desc: str | None = None,
             total: float | None = None,
             leave: bool | None = True,
             file: SupportsWrite[str] | None = None,
             ncols: int | None = None,
             mininterval: float = 0.1,
             maxinterval: float = 10.0,
             miniters: float | None = None,
             ascii: bool | str | None = None,
             disable: bool | None = False,
             unit: str = "it",
             unit_scale: bool | float = False,
             dynamic_ncols: bool = False,
             smoothing: float = 0.3,
             bar_format: str | None = None,
             initial: float = 0,
             position: int | None = None,
             postfix: Mapping[str, object] | str | None = None,
             unit_divisor: float = 1000,
             write_bytes: bool = False,
             lock_args: tuple[bool | None, float | None] | tuple[bool | None] | None = None,
             nrows: int | None = None,
             colour: str | None = None,
             delay: float | None = 0,
             gui: bool = False,
             **kwargs: Any) -> None

iterable

• type：可迭代对象
• 说明：传入任何可迭代对象，如列表、生成器等，tqdm 会自动遍历这个对象，并显示进度信息。

desc

• 说明：这个参数允许你在进度条前面添加一个自定义的描述，通常用于表示当前任务的内容。
  

total

• 说明：预期的迭代总次数。如果不设置，tqdm 将尝试从可迭代对象自动推断总数。

leave

• 说明：指定当进度条结束时是否保留其显示。如果设置为 False，当进度条完成时，它会自动消失。

ncols

• 说明：设置进度条的宽度（单位为字符）。如果指定，将动态调整进度条以保持在这个范围内。如果未指定，将尝试使用环境宽度。默认情况下，如果环境宽度无法获取，进度条的宽度为 10，且统计信息和计数器没有限制。如果设置为 0，则不打印任何进度条（只打印统计信息）。

file

• type：io.TextIOWrapper or io.StringIO
• default：sys.stderr
• 说明：指定输出进度条的文件流。使用 file.write(str) 和 file.flush() 方法进行输出。

mininterval 和 maxinterval

• 说明：mininterval 设置进度条更新的最小间隔时间（秒），即进度条信息刷新的频率，maxinterval 设置最大间隔时间（秒）。在长时间的显示更新延迟后，会自动调整 miniters 以对应 mininterval。只有在启用了 dynamic_miniters 或监视器线程时才有效。

miniters

• 说明：最小进度显示更新间隔，以迭代次数计。如果设置为 0 且启用了 dynamic_miniters，将自动调整以等于 mininterval，这对于紧密循环更为 CPU 高效。如果大于 0，则跳过指定数量的迭代不更新显示。根据你的进度条更新频繁或不频繁（如网络延迟、跳过项目等），你应该调整此值和 mininterval。

ascii

• 说明：如果未指定或为 False，使用 Unicode 字符填充进度条。如果为 True，则使用 ASCII 字符中的 “123456789#” 来填充进度条。

disable

• 说明：是否禁用整个进度条包装器。如果设置为 None，在非 TTY 环境中禁用。

unit

• default：’it’
• 说明：用于定义每次迭代单位的字符串。
  

unit_scale

• 说明：如果为 1 或 True，迭代次数将自动减少/缩放，并添加国际单位制前缀（如 kilo, mega 等）。如果是其他非零数值，将缩放 total 和 n。

dynamic_ncols

• 说明：如果设置为 True，进度条的宽度会动态调整以适应终端窗口的宽度变化（即不断更改 ncols 和 nrows）。

smoothing

• 说明：控制进度条的平滑度。更高的值意味着进度条速度更新更平缓，较低的值则反映更敏感的速度变化。范围从 0（平均速度）到 1（当前/瞬时速度）。

bar_format

• default：”{l_bar}{bar}{r_bar}”
• 说明：自定义进度条的格式，可能影响性能。可能的变量包括 l_bar, bar, r_bar, n, n_fmt 等。注意，如果 desc 为空，则会自动从 desc 后面移除尾随的 “: “。
  

initial

• 说明：初始计数器值。在重新启动进度条时很有用。如果使用浮点数，请考虑在 bar_format 中指定 {n:.3f} 或类似格式，或指定 unit_scale。

position

• 说明：指定打印此条的行偏移（从 0 开始）。如果未指定，则自动确定。在同时管理多个进度条时（例如，来自线程）很有用。
• 示例：

  from tqdm import trange
  from threading import Thread
  from time import sleep
  
  def task(position, name):
      for i in trange(100, position=position, desc=name):
          sleep(0.1)
  
  # 启动两个并行任务，每个都有自己的进度条
  Thread(target=task, args=(1, "Bar1",)).start()
  Thread(target=task, args=(2, "Bar2",)).start()

  
  

postfix

• 说明：指定在进度条末尾显示的附加统计信息。如果可能，调用 set_postfix(**postfix)（如果是字典）。

unit_divisor

• 说明：除非 unit_scale 为 True，否则忽略此参数。

write_bytes

• 说明：是否写入字节。如果为 False，将写入 unicode。

lock_args

• 说明：传递给 refresh 以用于中间输出（初始化、迭代和更新）。

nrows

• 说明：屏幕高度。如果指定，将隐藏超出此范围的嵌套条。如果未指定，将尝试使用环境高度。

colour

• 说明：进度条颜色（例如 ‘green’, ‘#00ff00’）

delay

• 说明：延迟显示进度条直到指定的时间秒数已经过去。

gui

• 说明：内部参数，不建议使用。如果需要图形化输出，请使用 tqdm.gui.tqdm(…) 而不是直接设置此参数。如果设置，将尝试使用 matplotlib 动画进行图形输出。

通过灵活使用这些参数，你可以让进度条更好地适应你的应用场景。

高级用法

手动更新

如果无法直接在循环中使用 tqdm，可以通过手动更新进度条的方式来控制它：

pbar = tqdm(total=100)
for i in range(10):
    # 执行一些操作...
    time.sleep(0.5)
    # 手动更新进度条，增加 10
    pbar.update(10)
pbar.close()

嵌套进度条

tqdm 也支持嵌套进度条，这在处理多层循环时非常有用：

from tqdm import trange
for i in trange(10, desc='Outer loop'):
    for j in trange(100, desc='Inner loop', leave=False):
        time.sleep(0.01)

使用 trange 代替 range，直接创建 tqdm 进度条

trange 是 tqdm(range(i)) 的简写形式。使用方法一致。

from tqdm import trange
import time

# 使用 trange 替代 range
for i in trange(100):
    time.sleep(0.1)  # 模拟任务

tqdm 是 Python 中一个非常实用的库，能够让长时间运行的程序更友好。通过进度条展示，用户可以实时了解程序的运行进度。本文介绍了 tqdm 的全部参数和一些高级用法，希望能帮助你在项目中有效地使用它。