Introduction

Yes, tqdm lets you show messages while a progress bar is running, but the right API depends on what kind of message you mean. For a changing label, use description or postfix APIs; for separate log lines, use tqdm.write so the progress bar stays readable.

Use set_description for a Short Left-Side Label

A description appears near the left side of the bar and is good for a compact phase name.

1from tqdm import tqdm
2import time
3
4with tqdm(total=5, desc="Loading") as pbar:
5    for i in range(5):
6        time.sleep(0.2)
7        pbar.set_description(f"Step {i}")
8        pbar.update(1)

Use this when the message is brief and conceptually labels the current step rather than reporting detailed metrics.

Use set_postfix for Live Key-Value Status

Postfix text is better for changing metrics such as loss, accuracy, file name, or retry count.

1from tqdm import tqdm
2import random
3
4with tqdm(total=10, desc="Train") as pbar:
5    for _ in range(10):
6        loss = random.random()
7        acc = 1 - loss / 2
8        pbar.set_postfix(loss=f"{loss:.4f}", acc=f"{acc:.3f}")
9        pbar.update(1)

This keeps the bar informative without flooding the console with separate print statements.

Use tqdm.write for Independent Messages

If you want a one-off message such as a warning or checkpoint line, tqdm.write is usually the right choice.

1from tqdm import tqdm
2
3for i in tqdm(range(5), desc="Process"):
4    if i == 2:
5        tqdm.write("Reached checkpoint i=2")

Unlike plain print, tqdm.write cooperates with the progress bar rendering so the output does not become messy.

Keep Update Frequency Reasonable

It is tempting to update descriptions or postfix text on every iteration, but that can add overhead and clutter.

If your loop is very fast, update the message only every few steps.

1from tqdm import tqdm
2
3with tqdm(total=1000) as pbar:
4    for i in range(1000):
5        if i % 100 == 0:
6            pbar.set_description(f"chunk {i // 100}")
7        pbar.update(1)

That gives useful feedback without turning the progress display itself into a performance problem.

Use set_postfix_str for Simple Free-Form Text

If your status message is not naturally a set of key-value pairs, set_postfix_str can be cleaner than set_postfix.

1from tqdm import tqdm
2
3with tqdm(total=3, desc="Download") as pbar:
4    for phase in ["connect", "transfer", "finalize"]:
5        pbar.set_postfix_str(phase)
6        pbar.update(1)

This is useful when you want a concise state string rather than several metrics.

Reserve bar_format for Custom Layouts

tqdm also lets you customize the full bar text layout with bar_format, but that is usually a formatting tool rather than the first answer to “how do I add a message.” Use it when the default layout no longer fits the information you need to display.

Notebook and Terminal Environments Differ

If you are in Jupyter, use the notebook-aware variant for better rendering.

from tqdm.notebook import tqdm

The same message APIs exist, but the visual behavior is often cleaner in notebook-specific widgets than in plain terminal output.

Common Pitfalls

• Using plain print repeatedly and breaking the visual layout of the bar.
• Updating description or postfix text far more often than the user can meaningfully read it.
• Treating descriptions and postfix metrics as interchangeable when they serve different display roles.
• Forgetting to use the notebook variant of tqdm in Jupyter environments.
• Turning the progress display into a logging stream instead of using it for concise status information.

Summary

• Use set_description for short changing labels.
• Use set_postfix for live metrics or key-value status.
• Use tqdm.write for separate message lines.
• 'set_postfix_str is handy for simple free-form status text.'
• Choose the tqdm variant that matches your environment.