tqdm — Fast Extensible Progress Bars for Python and CLI

Introduction

tqdm (Arabic for "progress") adds smart progress meters to any Python loop or CLI pipeline. It wraps iterables with minimal overhead (around 60ns per iteration) and auto-detects terminal width, notebook cells, and GUI environments to render the appropriate bar style.

What tqdm Does

• Wraps any iterable to display elapsed time, speed, and ETA
• Works in terminals, Jupyter notebooks, and GUI frameworks (tkinter, Qt)
• Provides a CLI mode for piping shell commands through a progress meter
• Supports nested bars, manual updates, and custom formatting
• Integrates with pandas via tqdm.pandas() for apply operations

Architecture Overview

tqdm is a pure-Python library with no required dependencies. It polls the system clock on each iteration and only refreshes the display at a configurable minimum interval (default 0.1s) to keep overhead negligible. The core tqdm class is subclassed for different frontends: tqdm.auto picks the right backend automatically, tqdm.notebook renders HTML widgets, and tqdm.gui uses matplotlib.

Self-Hosting & Configuration

• Install via pip, conda, or system package managers
• Use tqdm.auto to let tqdm choose terminal or notebook rendering
• Customize bar format with the bar_format parameter
• Set miniters and mininterval to control refresh frequency
• Use tqdm.write() instead of print() to avoid display corruption

Key Features

• Near-zero overhead at roughly 60 nanoseconds per iteration
• Automatic rate and ETA calculation with exponential smoothing
• Thread-safe and multiprocessing-compatible with tqdm.contrib.concurrent
• Rich integration ecosystem (pandas, Keras, Discord, Telegram bots)
• Supports asyncio iterables via tqdm.asyncio

Comparison with Similar Tools

• Rich Progress — part of the Rich library with more visual flair; tqdm is lighter and more widely adopted
• alive-progress — animated spinners and bars; tqdm has broader ecosystem integration
• progressbar2 — similar concept but tqdm is faster and has more active maintenance
• Click progress_bar — built into Click CLI framework; tqdm works independently of any framework
• enlighten — supports multiple simultaneous bars natively; tqdm achieves this via nesting

FAQ

Q: Does tqdm slow down my loop? A: The overhead is around 60ns per iteration. For any loop doing real work, it is negligible.

Q: How do I use tqdm with pandas? A: Call tqdm.pandas() once, then use df.progress_apply() instead of df.apply().

Q: Can I use tqdm in a Jupyter notebook? A: Yes. Use from tqdm.auto import tqdm and it renders HTML-based progress widgets automatically.

Q: How do I show multiple nested progress bars? A: Pass position=0, position=1, etc. and set leave=True or leave=False to control persistence.

Sources

• https://github.com/tqdm/tqdm
• https://tqdm.github.io