Visualize Python Script Progress with Tqdm: A Practical Guide

Long‑running Python programs often leave users guessing about their progress, leading to impatience and premature termination. The open‑source tqdm library (over 17 000 stars on GitHub) provides a simple way to visualize execution progress.

1. Introduction to tqdm

tqdm adds a lightweight, configurable progress bar to any iterable, making the status of loops and tasks clear at a glance.

2. How to Use

tqdm works in standard terminals and also integrates with Jupyter notebooks via the notebook submodule. The following conditional import detects the environment:

import sys
if hasattr(sys.modules["__main__"], "get_ipython"):
    from tqdm import notebook as tqdm
else:
    import tqdm

For a simple iterative task, you can wrap the loop with tqdm.trange:

def improve_guess(rt, n):
    return (rt + n/rt) / 2

guess = 1
target = 2
for i in tqdm.trange(10):
    guess = improve_guess(guess, target)

When processing a known number of items with similar execution time, such as computing the product of random numbers, wrap the iterable with tqdm.tqdm:

import random
numbers = [random.uniform(0, 2.8) for i in range(100)]
result = 1
for num in tqdm.tqdm(numbers):
    result *= num
print(result)

For tasks with unknown total work, such as downloading a large file, you can create a progress bar using the total size from the HTTP headers:

url = "https://www.python.org/ftp/python/3.9.0/Python-3.9.0.tgz"
import httpx
with httpx.stream("GET", url) as response:
    total = int(response.headers["Content-Length"])
    with tqdm.tqdm(total=total) as progress:
        for chunk in response.iter_bytes():
            progress.update(len(chunk))

Nested progress bars are useful when processing multiple files, each with its own progress tracking:

files = [f"vid-{i}.mp4" for i in range(4)]
for fname in tqdm.tqdm(files, desc="files"):
    total = random.randrange(10**9, 2*10**9)
    with tqdm.tqdm(total=total, desc=fname) as progress:
        current = 0
        while current < total:
            chunk_size = min(random.randrange(10**3, 10**5), total - current)
            current += chunk_size
            if random.uniform(0, 1) < 0.01:
                time.sleep(0.1)
            progress.update(chunk_size)

By displaying progress, long‑running Python programs become more user‑friendly and reduce frustration.