tqdm: A Fast, Extensible Progress Bar for Python and CLI

4.67.3 verified Tue May 12 auth: no python install: verified quickstart: verified

tqdm is a highly popular Python library that provides fast and extensible progress bars for loops and other iterable constructs. The name 'tqdm' is derived from the Arabic word 'taqaddum' (progress) and also stands for 'te quiero demasiado' (I love you so much). It seamlessly integrates with various Python libraries and environments, including Jupyter notebooks and command-line interfaces, allowing developers to easily monitor the progress of long-running tasks. The current stable version is 4.67.3, with frequent patch releases addressing bug fixes, performance enhancements, and compatibility updates.

pip install tqdm

Common errors

error ModuleNotFoundError: No module named 'tdqm' ↓

cause You likely mistyped `tqdm` as `tdqm` in your import statement. While a `tdqm` package exists on PyPI, it's a placeholder for common typos and does not provide `tqdm`'s functionality.

fix

Correct the import statement to from tqdm import tqdm or import tqdm. Ensure you have installed the correct package: pip install tqdm.

error AttributeError: module 'tqdm' has no attribute 'tqdm' (when using `import tqdm` then `tqdm(range(...)))` ↓

cause When you use `import tqdm`, you're importing the `tqdm` *module*. The `tqdm` function itself is an attribute of this module.

fix

Change your import to from tqdm import tqdm to directly import the function, or explicitly call tqdm.tqdm(range(...)) if you prefer the module import.

error Progress bar does not update in Jupyter/VS Code/Cloud environment. ↓

cause Output buffering in certain environments (like Jupyter, VS Code integrated terminal, or cloud logs) can prevent `tqdm` from redrawing the progress bar in place.

fix

For Jupyter: use from tqdm.notebook import tqdm (requires ipywidgets). For some cloud logging: set TQDM_POSITION=-1 environment variable. Ensure the Python interpreter selected in your IDE matches where tqdm is installed.

error TypeError: Progress.reset() missing 1 required positional argument: 'task_id' (specifically with `tqdm.rich` integration) ↓

cause This indicates an incompatibility or bug in how `tqdm`'s experimental `rich` integration handles the `reset()` method, specifically not passing a required `task_id` to `rich.progress.Progress.reset()`.

fix

This issue might be resolved in newer tqdm versions. Update tqdm to the latest stable release. If the problem persists, it may be a known bug in the experimental tqdm.rich module, consider using standard tqdm or tqdm.notebook for stability.

Warnings

breaking The `tdqm` package (version 0.0.1) on PyPI is an alias for typos of `tqdm` and does not provide the actual `tqdm` functionality. Installing `tdqm` will not give you the progress bar library. ↓

fix Always install `tqdm` using `pip install tqdm`. If you've installed `tdqm`, uninstall it with `pip uninstall tdqm`.

gotcha When using `tqdm` with Python's `multiprocessing` module, progress bars may not update correctly or can lead to 'endless loop of errors' if the multiprocessing pool is not properly initialized. ↓

fix Always encapsulate your main code within a function and call it under an `if __name__ == "__main__":` guard to ensure correct process initialization.

gotcha In Jupyter Notebooks and similar interactive environments, progress bars might not update immediately due to output buffering. ↓

fix Use `from tqdm.notebook import tqdm` or `from tqdm.auto import tqdm` for Jupyter-specific, interactive widgets. Ensure `ipywidgets` is installed.

deprecated The `gui` module (e.g., `tqdm.gui`) for Matplotlib GUI progress bars has experienced syntax fixes and is generally considered experimental. ↓

fix Update to `tqdm>=4.67.1` for fixes, but be aware that GUI integrations can be less stable than console/notebook bars. Consider alternative display methods if encountering persistent issues.

gotcha If your iterable has an unknown length (e.g., a generator), `tqdm` cannot calculate percentage or estimated time unless the `total` parameter is explicitly provided. ↓

fix If the total number of iterations is known, provide it as `tqdm(my_generator(), total=known_total)`. Otherwise, the bar will only show the count of completed iterations.

breaking The `cli` module in versions prior to `v4.66.3` had an `eval` safety vulnerability (CVE-2024-34062, GHSA-g7vv-2v7x-gj9p). ↓

fix Upgrade `tqdm` to version `4.66.3` or newer immediately.

Install

conda install -c conda-forge tqdm

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.14s 18.3M

3.10 slim (glibc) - - 0.10s 19M

3.11 alpine (musl) - - 0.20s 20.2M

3.11 slim (glibc) - - 0.15s 21M

3.12 alpine (musl) - - 0.17s 12.1M

3.12 slim (glibc) - - 0.17s 13M

3.13 alpine (musl) - - 0.14s 11.7M

3.13 slim (glibc) - - 0.20s 12M

3.9 alpine (musl) - - 0.12s 17.8M

3.9 slim (glibc) - - 0.10s 18M

Imports

tqdm
wrong
```
import tqdm
```
correct
```
from tqdm import tqdm
```
Importing `tqdm` as a module (`import tqdm`) requires using `tqdm.tqdm()` to wrap iterables, which is less common. Directly importing the `tqdm` function (`from tqdm import tqdm`) is the standard practice.
trange
```
from tqdm import trange
```
A convenient shortcut for `tqdm(range(N))`.
tqdm
```
from tqdm.notebook import tqdm
```
For displaying rich, interactive progress bars within Jupyter Notebooks and other IPython environments. Requires `ipywidgets`.
tqdm
```
from tqdm.auto import tqdm
```
Automatically selects between console (`tqdm.tqdm`) and notebook (`tqdm.notebook`) progress bars based on the environment.

Quickstart verified last tested: 2026-04-23

Wrap any iterable with `tqdm()` to instantly display a progress bar. For convenience with `range`, use `trange()`. For pandas DataFrames, register `tqdm.pandas()` and then use `progress_apply()` or `progress_map()`.

import time
from tqdm import tqdm

for i in tqdm(range(100), desc="Processing items"): 
    time.sleep(0.05)
print("Done!")

# For pandas integration:
# import pandas as pd
# import numpy as np
# from tqdm.auto import tqdm
# tqdm.pandas()
# df = pd.DataFrame(np.random.randint(0, 100, (100, 3)))
# df.progress_apply(lambda x: x * 2)