使用 tqdm 在 Python 中跟踪进度

最后修改日期：2025 年 3 月 31 日

Python 的 tqdm 库提供了一种简单的方式为您的循环和任务添加进度条。本教程通过各种场景的实际示例，涵盖了其安装、基本用法和高级功能。

跟踪进度对于长时间运行的操作至关重要，无论您是正在处理文件、训练模型还是遍历大型数据集。我们将探讨 tqdm 如何通过最小的代码更改来简化这一过程。

安装和基本设置

首先，使用 pip 安装 tqdm 并在您的 Python 脚本中导入它。

tqdm_install.py

# Install via pip
# pip install tqdm

from tqdm import tqdm
import time

# Basic loop with progress bar
for i in tqdm(range(100)):
    time.sleep(0.1)  # Simulate work

要使用 tqdm，请使用 pip install tqdm 进行安装。基本用法是将任何可迭代对象包装在 tqdm() 中，即可立即添加进度条。在此示例中，我们使用 time.sleep 来模拟工作，以便查看进度条的更新。输出显示了一个动态进度条，包含百分比、迭代次数和剩余估计时间，所有这些都由 tqdm 自动处理。

自定义进度条

您可以通过参数来自定义 tqdm 的外观和行为。

tqdm_custom.py

from tqdm import tqdm
import time

# Custom description and bar format
for i in tqdm(range(100), desc="Processing", bar_format="{l_bar}{bar}| {n_fmt}/{total_fmt}"):
    time.sleep(0.05)

desc 参数在进度条前面添加一个前缀，而 bar_format 允许您定义布局。在这里，我们仅显示进度条和迭代计数，省略了额外的统计信息。这对于在特定应用程序中进行定制化显示非常有用，可以保持输出的整洁和专注。

跟踪文件处理

使用 tqdm 来监控文件操作，例如读取行。

tqdm_file.py

from tqdm import tqdm

# Process a file line by line
with open('large_file.txt', 'r') as f:
    total_lines = sum(1 for _ in f)  # Count lines
    f.seek(0)  # Reset file pointer
    for line in tqdm(f, total=total_lines, desc="Reading file"):
        pass  # Process line here

对于文件操作，tqdm 可以通过设置 total 参数来跟踪进度。在这里，我们预先计算行数以提供准确的进度条。这对于处理大型文件的脚本非常理想，可以在不猜测完成时间的情况下提供有关剩余工作量的反馈。

嵌套循环与 tqdm

为嵌套迭代处理多个进度条。

tqdm_nested.py

from tqdm import tqdm
import time

# Nested loops with separate bars
for i in tqdm(range(5), desc="Outer"):
    for j in tqdm(range(10), desc="Inner", leave=False):
        time.sleep(0.1)

Tqdm 支持嵌套循环，通过创建多个进度条。leave=False 选项会在内层进度条完成后将其移除，保持输出整洁。这对于多步过程（如网格搜索或模拟）非常理想，可以清晰地显示每个级别的进度。

手动更新进度

为非可迭代任务手动更新进度。

tqdm_manual.py

from tqdm import tqdm
import time

# Manual control of progress
with tqdm(total=100, desc="Manual Task") as pbar:
    for i in range(10):
        time.sleep(0.2)
        pbar.update(10)  # Update by 10 units

对于没有自然可迭代对象（iterable）的任务，请将 tqdm 用作上下文管理器。update() 方法会手动增加进度条。此示例模拟了一个分为 10 个块的任务，每次更新 10%。这对于自定义工作流（如 API 调用或下载）非常有用。

列表推导式与进度

使用 tqdm 跟踪列表推导式中的进度。

tqdm_listcomp.py

from tqdm import tqdm
import time

# List comprehension with progress
result = [x * 2 for x in tqdm(range(100), desc="Computing")]
time.sleep(0.1)  # Simulate work after

在列表推导式中用 tqdm 包装可迭代对象以添加进度条。请注意，推导式之后的额外工作除非移到内部，否则将不会被跟踪。这在增加可见性的同时，保持了 Python 的简洁语法，对于快速数据转换非常有用。

与 Pandas 集成

在数据处理任务中使用 tqdm 和 Pandas。

tqdm_pandas.py

import pandas as pd
from tqdm import tqdm

# Enable tqdm for pandas
tqdm.pandas()

# Process DataFrame rows
df = pd.DataFrame({'a': range(1000)})
df['b'] = df['a'].progress_apply(lambda x: x * 2)

Tqdm 通过 tqdm.pandas() 与 Pandas 集成。progress_apply 方法可以跟踪 DataFrame 行或列上的操作。在这里，我们通过进度条将列 'a' 中的每个值乘以两倍。这对于具有大型数据集的数据分析任务非常宝贵，可以在不更改 Pandas 工作流程的情况下显示进度。

最佳实践

已知时设置总数： 提高 ETA 准确性
使用 desc 以获得清晰度： 标记正在跟踪的内容
处理嵌套进度条： 内层循环使用 leave=False
测试输出： 确保进度条适合您的终端大小
避免过度使用： 仅用于重要操作

资料来源

作者

我叫 Jan Bodnar，是一名充满激情的程序员，拥有丰富的编程经验。自 2007 年以来，我一直在撰写编程文章。至今，我已撰写了 1,400 多篇文章和 8 本电子书。我在编程教学方面拥有十多年的经验。

列出所有 Python 教程。