# pydoc > tqdm.std.tqdm

---
type: CommandReference
command: tqdm
mode: pydoc
section: 
source: pydoc3
---

## Quick Reference
- `for x in tqdm(iterable):` — wrap an iterable for automatic progress updates.
- `t = tqdm(total=100)` — manual progress bar with total.
- `t.update(10)` — manually increment progress.
- `t.close()` — cleanup and close the bar.
- `tqdm.pandas(desc='Processing')` — register `progress_apply` for pandas.
- `with tqdm.wrapattr(file_obj, 'read', total=size) as fobj:` — wrap file read/write.

## Name
`tqdm` — Decorate an iterable object, returning an iterator that prints a dynamically updating progress bar.

## Synopsis
python
class tqdm(iterable=None, desc=None, total=None, leave=True, file=None, ncols=None,
           mininterval=0.1, maxinterval=10.0, miniters=None, ascii=None, disable=False,
           unit='it', unit_scale=False, dynamic_ncols=False, smoothing=0.3,
           bar_format=None, initial=0, position=None, postfix=None,
           unit_divisor=1000, write_bytes=False, lock_args=None, nrows=None,
           colour=None, delay=0.0, gui=False, **kwargs)
## Options
- `iterable` — iterable to decorate. Leave blank for manual updates.
- `desc` — prefix for the progress bar.
- `total` — expected iterations. If `None`, uses `len(iterable)` if possible. If `float("inf")`, only basic stats shown.
- `leave` — if `True` (default), keeps all traces upon termination. If `None`, leaves only if `position` is `0`.
- `file` — output stream (`io.TextIOWrapper` or `io.StringIO`). Default: `sys.stderr`.
- `ncols` — width of output message. Dynamic resize if unspecified. `0` disables the meter (only stats).
- `mininterval` — minimum update interval in seconds (default `0.1`).
- `maxinterval` — maximum update interval in seconds (default `10`). Adjusts `miniters` after long lag.
- `miniters` — minimum update interval in iterations. If `0` and `dynamic_miniters`, auto-adjusts to `mininterval`. If >0, skips display for that many iterations.
- `ascii` — if `False` or not set, uses unicode smooth blocks. If `True` or a string, uses ASCII characters `" 123456789#"`.
- `disable` — if `True`, disables the progress bar. `None` disables on non-TTY (default `False`).
- `unit` — unit string for iterations (default `'it'`).
- `unit_scale` — if `True` or `1`, scales numbers with SI prefixes (k, M, etc.). If any other non-zero number, scales `total` and `n`.
- `dynamic_ncols` — if `True`, constantly adjusts `ncols` and `nrows` to terminal size (default `False`).
- `smoothing` — exponential moving average smoothing factor for speed (0=average, 1=instantaneous). Default `0.3`.
- `bar_format` — custom format string. Default: `'{l_bar}{bar}{r_bar}'`. Available vars: `l_bar`, `bar`, `r_bar`, `n`, `n_fmt`, `total`, `total_fmt`, `percentage`, `elapsed`, `elapsed_s`, `ncols`, `nrows`, `desc`, `unit`, `rate`, `rate_fmt`, `rate_noinv`, `rate_noinv_fmt`, `rate_inv`, `rate_inv_fmt`, `postfix`, `unit_divisor`, `remaining`, `remaining_s`, `eta`.
- `initial` — initial counter value (default `0`). Useful for restarts.
- `position` — line offset for multiple bars. Automatic if not specified.
- `postfix` — dict or additional stats displayed at the end of the bar.
- `unit_divisor` — divisor for unit scaling (default `1000`). Ignored unless `unit_scale` is `True`.
- `write_bytes` — if `True`, writes bytes; otherwise unicode.
- `lock_args` — passed to `refresh` for intermediate output.
- `nrows` — screen height, hides nested bars beyond this bound. Default: environment height, fallback 20.
- `colour` — bar colour (e.g. `'green'`, `'#00ff00'`).
- `delay` — seconds to wait before first display (default `0`).
- `gui` — internal parameter. Use `tqdm.gui.tqdm()` instead.

## Methods

### Instance Methods
- `__init__` — constructor (see Options).
- `__iter__` — backward-compatible iteration: `for x in tqdm(iterable)`.
- `__len__` — returns length of iterable or total.
- `__reversed__` — reverse iteration.
- `__str__` — returns string representation.
- `__bool__` — truth value.
- `__contains__` — membership test.
- `__del__` — cleanup.
- `__enter__` / `__exit__` — context manager support.
- `__hash__` — hash.
- `clear(nolock=False)` — clear current bar display.
- `close()` — cleanup and (if `leave=False`) close the progress bar.
- `display(msg=None, pos=None)` — display `msg` at specified position. Override for custom frontends.
- `moveto(n)` — move cursor to line `n`.
- `refresh(nolock=False, lock_args=None)` — force refresh the display.
- `reset(total=None)` — reset iterations to 0 for repeated use. Optionally set new total.
- `set_description(desc=None, refresh=True)` — set/modify description.
- `set_description_str(desc=None, refresh=True)` — set description without trailing `': '`.
- `set_postfix(ordered_dict=None, refresh=True, **kwargs)` — set postfix with automatic formatting.
- `set_postfix_str(s='', refresh=True)` — set postfix string directly.
- `unpause()` — restart tqdm timer from last print time.
- `update(n=1)` — manually increment internal counter by `n`. Returns `True` if display was triggered.

### Class Methods
- `external_write_mode(file=None, nolock=False)` — context manager to disable tqdm and refresh after.
- `get_lock()` — get the global lock, constructing it if needed.
- `pandas(**tqdm_kwargs)` — register `tqdm` for `pandas` `progress_apply`.
- `set_lock(lock)` — set the global lock.
- `wrapattr(stream, method, total=None, bytes=True, **tqdm_kwargs)` — wrap a file-like object's `read` or `write` method with a progress bar.
- `write(s, file=None, end='\n', nolock=False)` — print a message via tqdm without overlapping bars.

### Static Methods
- `format_interval(t)` — format seconds as `[H:]MM:SS`.
- `format_meter(n, total, elapsed, ncols=None, prefix='', ascii=False, unit='it', unit_scale=False, rate=None, bar_format=None, postfix=None, unit_divisor=1000, initial=0, colour=None, **extra_kwargs)` — return a formatted progress bar string.
- `format_num(n)` — intelligent scientific notation (`.3g`).
- `format_sizeof(num, suffix='', divisor=1000)` — format a number with SI unit prefixes.
- `status_printer(file)` — manage in-place line printing.

### Readonly Properties
- `format_dict` — public API for read-only member access (includes `n`, `total`, `elapsed`, etc.).

### Data Attributes
- `monitor` — `None` (monitor thread).
- `monitor_interval` — `10` (seconds).

## Examples
python
# Basic usage
from tqdm import tqdm
for i in tqdm(range(100)):
    pass

# Manual control
t = tqdm(total=100)
for i in range(10):
    t.update(10)
t.close()

# Wrap a file read
with tqdm.wrapattr(open('file.txt'), 'read', total=filesize) as fobj:
    chunk = fobj.read(chunk_size)

# Pandas integration
import pandas as pd
import numpy as np
from tqdm import tqdm
df = pd.DataFrame(np.random.randint(0, 100, (100000, 6)))
tqdm.pandas(desc='Processing')
df.groupby(0).progress_apply(lambda x: x**2)
## See Also
- [tqdm documentation](https://tqdm.github.io/)
- `tqdm.gui` — graphical progress bars
- `tqdm.notebook` — Jupyter notebook widgets
- `tqdm.contrib` — community extensions
- `pandas` — data analysis library