pydoc > tqdm.std.tqdm

man perldoc info pydoc3 ri search

📦 NAME

tqdm.std.tqdm — Decorate an iterable object, returning an iterator which acts exactly like the original iterable, but prints a dynamically updating progress bar every time a value is requested.

🚀 Quick Reference

Use Case	Command	Description
📋 Basic iterable	for i in tqdm(range(100)):	Wrap any iterable with a progress bar
📡 Manual update	t = tqdm(total=filesize); t.update(len(buf))	Manually advance the bar (e.g., streaming)
🧵 Context manager	with tqdm(total=100) as pbar:	Auto-cleanup on exit
🐼 pandas integration	tqdm.pandas(); df.progress_apply(func)	Progress bars for pandas apply methods
📝 Write messages	tqdm.write('Log message')	Print without overlapping the bar
⏱️ Reset bar	pbar.reset(total=200)	Reuse a progress bar with a new total

⚙️ OPTIONS

• iterable : iterable, optional
  📥 Iterable to decorate with a progress bar. Leave blank to manually manage updates.
• desc : str, optional
  🏷️ Prefix for the progress bar.
• total : int or float, optional
  🔢 Expected number of iterations. If unspecified, len(iterable) is used if possible. If float("inf") or as a last resort, only basic statistics are displayed (no ETA, no progress bar). If gui is True and this needs later updating, specify an initial large positive number, e.g. 9e9.
• leave : bool, optional
  🚪 If [default: True], keeps all traces of the progress bar upon termination. If None, will leave only if position is 0.
• file : io.TextIOWrapper or io.StringIO, optional
  📁 Where to output the progress messages (default: sys.stderr). Uses file.write(str) and file.flush(). For encoding, see write_bytes.
• ncols : int, optional
  📏 Width of the entire output message. Dynamically resizes the bar to stay within this bound. If 0, only stats are printed (no bar).
• mininterval : float, optional
  ⏱️ Minimum display update interval [default: 0.1] seconds.
• maxinterval : float, optional
  ⏰ Maximum display update interval [default: 10] seconds. Automatically adjusts miniters after long lag. Only works if dynamic_miniters or monitor thread is enabled.
• miniters : int or float, optional
  🔁 Minimum display update interval in iterations. If 0 and dynamic_miniters, will automatically adjust to equal mininterval (more CPU efficient). If > 0, skips display of that many iterations. For erratic loops (network, skipping items), set miniters=1.
• ascii : bool or str, optional
  🅰️ If unspecified or False, use unicode smooth blocks. Fallback uses ASCII characters " 123456789#".
• disable : bool, optional
  🚫 Disable the entire progress bar wrapper [default: False]. If None, disable on non-TTY.
• unit : str, optional
  📦 Unit of each iteration [default: 'it'].
• unit_scale : bool or int or float, optional
  📐 If 1 or True, the number of iterations is scaled automatically with SI prefixes (kilo, mega, etc.) [default: False]. If any other non-zero number, scales total and n.
• dynamic_ncols : bool, optional
  🔄 Constantly alter ncols and nrows to the environment (allowing for window resizes) [default: False].
• smoothing : float, optional
  📈 Exponential moving average smoothing factor for speed estimates (0 = average, 1 = instantaneous) [default: 0.3]. Ignored in GUI mode.
• bar_format : str, optional
  🎨 Custom bar string formatting. Default: '{l_bar}{bar}{r_bar}'. Possible variables: 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. A trailing ": " is removed after {desc} if empty.
• initial : int or float, optional
  🔢 Initial counter value [default: 0]. Useful when restarting a bar. If using float, consider {n:.3f} in bar_format or unit_scale.
• position : int, optional
  📍 Line offset to print this bar (starting from 0). Automatic if unspecified. Useful for multiple bars (e.g., threads).
• postfix : dict or *, optional
  ➕ Additional stats to display at the end of the bar. Calls set_postfix(**postfix) if dict.
• unit_divisor : float, optional
  🔢 Divisor for unit scaling [default: 1000], ignored unless unit_scale is True.
• write_bytes : bool, optional
  🔤 Whether to write bytes. If (default: False) writes unicode.
• lock_args : tuple, optional
  🔒 Passed to refresh for intermediate output (initialisation, iterating, updating).
• nrows : int, optional
  📏 Screen height. Hides nested bars outside this bound. Fallback is 20.
• colour : str, optional
  🎨 Bar colour (e.g. 'green', '#00ff00').
• delay : float, optional
  ⏳ Don't display until [default: 0] seconds have elapsed.
• gui : bool, optional
  ⚠️ WARNING: internal parameter. Use tqdm.gui.tqdm(...) instead. If set, attempts to use matplotlib animations.

📤 Returns

out : decorated iterator.

🔧 Methods

📜 Method Resolution Order

1. tqdm
2. tqdm.utils.Comparable
3. builtins.object

🟢 Instance Methods

• __bool__(self)
• __contains__(self, item)
• __del__(self)
• __enter__(self)
• __exit__(self, exc_type, exc_value, traceback)
• __hash__(self) — Return hash(self).
• __init__(self, 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)
• __iter__(self) — Backward-compatibility to use: for x in tqdm(iterable)
• __len__(self)
• __reversed__(self)
• __str__(self) — Return str(self).
• clear(self, nolock=False) — Clear current bar display.
• close(self) — Cleanup and (if leave=False) close the progress bar.
• display(self, msg=None, pos=None) — Use self.sp to display msg in the specified pos. Consider overloading when inheriting. Parameters:
  • msg : str, optional. What to display (default: repr(self)).
  • pos : int, optional. Position to moveto (default: abs(self.pos)).
• moveto(self, n)
• refresh(self, nolock=False, lock_args=None) — Force refresh the display of this bar. Parameters:
  • nolock : bool, optional. If True, does not lock. Default: False calls acquire() on internal lock.
  • lock_args : tuple, optional. Passed to internal lock's acquire(). If specified, will only display() if acquire() returns True.
• reset(self, total=None) — Resets to 0 iterations for repeated use. Consider combining with leave=True. Parameters:
  • total : int or float, optional. Total to use for the new bar.
• set_description(self, desc=None, refresh=True) — Set/modify description of the progress bar. Parameters:
  • desc : str, optional
  • refresh : bool, optional. Forces refresh [default: True].
• set_description_str(self, desc=None, refresh=True) — Set/modify description without ': ' appended.
• set_postfix(self, ordered_dict=None, refresh=True, **kwargs) — Set/modify postfix (additional stats) with automatic formatting based on datatype. Parameters:
  • ordered_dict : dict or OrderedDict, optional
  • refresh : bool, optional. Forces refresh [default: True].
  • kwargs : dict, optional
• set_postfix_str(self, s='', refresh=True) — Postfix without dictionary expansion, similar to prefix handling.
• unpause(self) — Restart tqdm timer from last print time.
• update(self, n=1) — Manually update the progress bar, useful for streams such as reading files.

  >>> t = tqdm(total=filesize) # Initialise
  >>> for current_buffer in stream:
  ...    ...
  ...    t.update(len(current_buffer))
  >>> t.close()

  The last line is highly recommended, but possibly not necessary if t.update() will exactly reach filesize and print. Parameters:
  • n : int or float, optional. Increment to add to the internal counter [default: 1]. If using float, consider {n:.3f} in bar_format or unit_scale.
  Returns: out : bool or None — True if a display() was triggered.

🏛️ Class Methods

• external_write_mode(file=None, nolock=False) — Disable tqdm within context and refresh tqdm when exits. Useful when writing to standard output stream.
• get_lock() — Get the global lock. Construct it if it does not exist.
• pandas(**tqdm_kwargs) — Registers the current tqdm class with pandas.core (DataFrame, Series, GroupBy) progress_apply. A new instance is created every time progress_apply is called, and each instance will automatically close() upon completion. Parameters: tqdm_kwargs : arguments for the tqdm instance.

  >>> import pandas as pd
  >>> import numpy as np
  >>> from tqdm import tqdm
  >>> from tqdm.gui import tqdm as tqdm_gui
  >>>
  >>> df = pd.DataFrame(np.random.randint(0, 100, (100000, 6)))
  >>> tqdm.pandas(ncols=50)  # can use tqdm_gui, optional kwargs, etc
  >>> # Now you can use `progress_apply` instead of `apply`
  >>> df.groupby(0).progress_apply(lambda x: x**2)

  References: https://stackoverflow.com/questions/18603270/ progress-indicator-during-pandas-operations-python
• set_lock(lock) — Set the global lock.
• wrapattr(stream, method, total=None, bytes=True, **tqdm_kwargs) — stream : file-like object. method : str, "read" or "write". The result of read() and the first argument of write() should have a len().

  >>> with tqdm.wrapattr(file_obj, "read", total=file_obj.size) as fobj:
  ...     while True:
  ...         chunk = fobj.read(chunk_size)
  ...         if not chunk:
  ...             break

• write(s, file=None, end='\n', nolock=False) — Print a message via tqdm (without overlap with bars).

⚙️ Static Methods

• __new__(cls, *_, **__) — Create and return a new object. See help(type) for accurate signature.
• format_interval(t) — Formats a number of seconds as a clock time, [H:]MM:SS. Parameters: t : int, number of seconds. Returns: out : str, [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 string-based progress bar. Parameters:
  • n : int or float, finished iterations
  • total : int or float, expected total. If None, only basic stats (no ETA)
  • elapsed : float, seconds since start
  • ncols : int, optional. Width of the output message. 0 suppresses bar
  • prefix : str, optional. Prefix message (included in total width)
  • ascii : bool or str, optional. Use unicode blocks or ASCII fallback
  • unit : str, optional. Iteration unit [default: 'it']
  • unit_scale : bool or int or float, optional. SI prefix scaling
  • rate : float, optional. Manual override for iteration rate
  • bar_format : str, optional. Custom bar string formatting
  • postfix : *, optional. Additional stats at the end
  • unit_divisor : float, optional. Default 1000
  • initial : int or float, optional. Initial counter value
  • colour : str, optional. Bar colour
  Returns: formatted meter and stats, ready to display.
• format_num(n) — Intelligent scientific notation (.3g). Parameters: n : int or float or Numeric. Returns: formatted number string.
• format_sizeof(num, suffix='', divisor=1000) — Formats a number (>= 1) with SI Order of Magnitude prefixes. Parameters: num : float, number to format; suffix : str, optional; divisor : float, optional. Returns: formatted string.
• status_printer(file) — Manage the printing and in-place updating of a line of characters. Note that if the string is longer than a line, in-place updating may not work (it will print a new line at each refresh).

📖 Readonly Properties

• format_dict — Public API for read-only member access.

🗂️ Data and Other Attributes

• monitor = None
• monitor_interval = 10

🔄 Inherited Methods (from tqdm.utils.Comparable)

• __eq__(self, other) — Return self==value.
• __ge__(self, other) — Return self>=value.
• __gt__(self, other) — Return self>value.
• __le__(self, other) — Return self<=value.
• __lt__(self, other) — Return self<value.
• __ne__(self, other) — Return self!=value.

📦 Inherited Data Descriptors

• __dict__ — dictionary for instance variables
• __weakref__ — list of weak references to the object

📦 NAME 🚀 Quick Reference ⚙️ OPTIONS 📤 Returns 🔧 Methods