0
# tqdm
1

2
A fast, extensible progress meter for loops and iterators in Python. tqdm wraps any iterable to create smart progress bars with minimal overhead (60ns per iteration) and works across all environments including terminals, GUIs, and Jupyter notebooks.
3

4
## Package Information
5

6
- **Package Name**: tqdm
7
- **Version**: 4.67.1
8
- **Language**: Python
9
- **Installation**: `pip install tqdm`
10
- **Dependencies**: None (optional: colorama on Windows)
11
- **License**: MPL-2.0 AND MIT
12
- **Python Support**: 3.7+
13
- **Homepage**: https://tqdm.github.io
14
- **Repository**: https://github.com/tqdm/tqdm
15

16
## Core Imports
17

18
```python
19
from tqdm import tqdm, trange
20
```
21

22
For specific environments and integrations:
23

24
```python
25
from tqdm.auto import tqdm, trange              # Auto-detects best variant
26
from tqdm.notebook import tqdm, trange          # Jupyter notebooks
27
from tqdm.asyncio import tqdm, trange           # Async/await support
28
from tqdm.gui import tqdm, trange              # Matplotlib GUI
29
from tqdm.rich import tqdm, trange             # Rich integration
30
from tqdm.contrib.concurrent import thread_map, process_map  # Parallel processing
31
```
32

33
## Basic Usage
34

35
```python
36
from tqdm import tqdm, trange
37
import time
38

39
# Wrap any iterable
40
for i in tqdm(range(10000)):
41
    time.sleep(0.0001)  # Simulate work
42

43
# Range shortcut
44
for i in trange(10000, desc="Processing"):
45
    time.sleep(0.0001)
46

47
# Manual updates
48
pbar = tqdm(total=100)
49
for i in range(100):
50
    time.sleep(0.01)
51
    pbar.update(1)
52
pbar.close()
53

54
# Context manager
55
with tqdm(total=100) as pbar:
56
    for i in range(100):
57
        time.sleep(0.01)
58
        pbar.update(1)
59

60
# Custom formatting
61
for i in tqdm(range(1000), desc="Training", unit="batch", 
62
              bar_format="{l_bar}{bar:30}{r_bar}"):
63
    time.sleep(0.001)
64
```
65

66
## Architecture
67

68
tqdm uses a modular architecture enabling extensive customization and multiple interfaces:
69

70
- **Core Engine** (`tqdm.std`): Foundation progress bar with format strings, timing, and display logic
71
- **Environment Variants**: Specialized implementations for different contexts (CLI, notebooks, GUI, async)
72
- **Integration Modules**: Extensions for popular frameworks (Keras, Dask, Pandas)
73
- **Utility Classes**: Thread-safe I/O wrappers, monitoring threads, and helper functions
74
- **Contrib Package**: Additional tools for parallel processing, itertools integration, and external services
75

76
This design allows tqdm to automatically adapt to any environment while providing consistent APIs across all variants.
77

78
## Capabilities
79

80
### Core Progress Bars
81

82
Essential progress bar functionality including iterator wrapping, manual updates, customizable formatting, and context manager support. Forms the foundation for all tqdm variants.
83

84
```python { .api }
85
class tqdm(Comparable):
86
    def __init__(self, iterable=None, desc=None, total=None, leave=True, 
87
                 file=None, ncols=None, mininterval=0.1, maxinterval=10.0,
88
                 miniters=None, ascii=None, disable=False, unit='it',
89
                 unit_scale=False, dynamic_ncols=False, smoothing=0.3,
90
                 bar_format=None, initial=0, position=None, postfix=None,
91
                 unit_divisor=1000, write_bytes=None, lock_args=None,
92
                 nrows=None, colour=None, delay=0, gui=False, **kwargs): ...
93
    
94
    def update(self, n=1): ...
95
    def close(self): ...
96
    def set_description(self, desc=None, refresh=True): ...
97
    def set_postfix(self, ordered_dict=None, refresh=True, **kwargs): ...
98

99
def trange(*args, **kwargs): ...
100
```
101

102
[Core Progress Bars](./core.md)
103

104
### Environment Variants
105

106
Specialized progress bar implementations for different environments including automatic selection, Jupyter notebooks, async/await support, and GUI interfaces.
107

108
```python { .api }
109
# Auto-detection
110
from tqdm.auto import tqdm, trange
111

112
# Jupyter notebooks  
113
from tqdm.notebook import tqdm as notebook_tqdm, trange as notebook_trange
114

115
# Async support
116
from tqdm.asyncio import tqdm as async_tqdm, trange as async_trange
117

118
# GUI variants
119
from tqdm.gui import tqdm as gui_tqdm
120
from tqdm.rich import tqdm as rich_tqdm
121
```
122

123
[Environment Variants](./environments.md)
124

125
### Framework Integrations
126

127
Integration modules for popular Python frameworks including Keras callbacks, Dask computation tracking, and pandas DataFrame operations.
128

129
```python { .api }
130
# Keras integration
131
from tqdm.keras import TqdmCallback
132

133
# Dask integration  
134
from tqdm.dask import TqdmCallback
135

136
# Pandas integration
137
tqdm.pandas()  # Enables .progress_apply() methods
138
```
139

140
[Framework Integrations](./integrations.md)
141

142
### Parallel Processing
143

144
Utilities for parallel processing with progress tracking including thread-based and process-based mapping functions with automatic progress bars.
145

146
```python { .api }
147
from tqdm.contrib.concurrent import thread_map, process_map
148

149
def thread_map(fn, *iterables, max_workers=None, chunksize=1, **tqdm_kwargs): ...
150
def process_map(fn, *iterables, max_workers=None, chunksize=1, **tqdm_kwargs): ...
151
```
152

153
[Parallel Processing](./parallel.md)
154

155
### Utilities and Extensions
156

157
Additional utilities including iterator helpers, logging integration, external service notifications, and low-level I/O wrappers for advanced use cases.
158

159
```python { .api }
160
from tqdm.contrib import tenumerate, tzip, tmap
161
from tqdm.contrib.logging import tqdm_logging_redirect
162
from tqdm.utils import FormatReplace, CallbackIOWrapper
163
```
164

165
[Utilities and Extensions](./utilities.md)
166

167
## Common Patterns
168

169
### Progress Bar Customization
170

171
```python
172
# Custom description and units
173
for i in tqdm(range(1000), desc="Processing items", unit="item"):
174
    pass
175

176
# Custom bar format
177
for i in tqdm(range(1000), 
178
              bar_format="{desc}: {percentage:3.0f}%|{bar}| {n_fmt}/{total_fmt}"):
179
    pass
180

181
# Dynamic postfix updates
182
pbar = tqdm(range(1000))
183
for i in pbar:
184
    pbar.set_postfix({"loss": f"{i*0.001:.3f}", "accuracy": f"{95+i*0.01:.1f}%"})
185
```
186

187
### Multiple Progress Bars
188

189
```python
190
from tqdm import tqdm
191
import time
192

193
# Sequential bars
194
for epoch in trange(5, desc="Epochs"):
195
    for batch in trange(100, desc="Batches", leave=False):
196
        time.sleep(0.01)
197

198
# Nested bars with position
199
outer = tqdm(range(5), desc="Outer", position=0)
200
for i in outer:
201
    inner = tqdm(range(100), desc=f"Inner {i}", position=1, leave=False)
202
    for j in inner:
203
        time.sleep(0.001)
204
    inner.close()
205
outer.close()
206
```
207

208
### Error Handling
209

210
```python
211
from tqdm import TqdmWarning, TqdmKeyError
212
import warnings
213

214
# Handle tqdm-specific warnings
215
with warnings.catch_warnings():
216
    warnings.simplefilter("ignore", TqdmWarning)
217
    # Your tqdm code here
218

219
# Exception handling
220
try:
221
    pbar = tqdm(total=100)
222
    # Progress bar operations
223
except TqdmKeyError as e:
224
    print(f"Configuration error: {e}")
225
finally:
226
    pbar.close()
227
```