Description
|Logo| tqdm ==== |Py-Versions| |Versions| |Conda-Forge-Status| |Docker| |Snapcraft| |Build-Status| |Coverage-Status| |Branch-Coverage-Status| |Codacy-Grade| |Libraries-Rank| |PyPI-Downloads| |LICENCE| |OpenHub-Status| |binder-demo| |awesome-python| ``tqdm`` derives from the Arabic word *taqaddum* (ΨͺΩΨ―ΩΩ ) which can mean "progress," and is an abbreviation for "I love you so much" in Spanish (*te quiero demasiado*). Instantly make your loops show a smart progress meter - just wrap any iterable with ``tqdm(iterable)``, and you're done! .. code:: python from tqdm import tqdm for i in tqdm(range(10000)): ... ``76%|ββββββββββββββββββββββββ Β Β Β Β Β Β | 7568/10000 [00:33<00:10, 229.00it/s]`` ``trange(N)`` can be also used as a convenient shortcut for ``tqdm(range(N))``. |Screenshot| |Video| |Slides| |Merch| It can also be executed as a module with pipes: .. code:: sh $ seq 9999999 | tqdm --bytes | wc -l 75.2MB [00:00, 217MB/s] 9999999 $ tar -zcf - docs/ | tqdm --bytes --total `du -sb docs/ | cut -f1` \ > backup.tgz 32%|βββββββββββ | 8.89G/27.9G [00:42<01:31, 223MB/s] Overhead is low -- about 60ns per iteration (80ns with ``tqdm.gui``), and is unit tested against performance regression. By comparison, the well-established `ProgressBar <https://github.com/niltonvolpato/python-progressbar>`__ has an 800ns/iter overhead. In addition to its low overhead, ``tqdm`` uses smart algorithms to predict the remaining time and to skip unnecessary iteration displays, which allows for a negligible overhead in most cases. ``tqdm`` works on any platform (Linux, Windows, Mac, FreeBSD, NetBSD, Solaris/SunOS), in any console or in a GUI, and is also friendly with IPython/Jupyter notebooks. ``tqdm`` does not require any dependencies (not even ``curses``!), just Python and an environment supporting ``carriage return \r`` and ``line feed \n`` control characters. ------------------------------------------ .. contents:: Table of contents :backlinks: top :local: Installation ------------ Latest PyPI stable release ~~~~~~~~~~~~~~~~~~~~~~~~~~ |Versions| |PyPI-Downloads| |Libraries-Dependents| .. code:: sh pip install tqdm Latest development release on GitHub ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |GitHub-Status| |GitHub-Stars| |GitHub-Commits| |GitHub-Forks| |GitHub-Updated| Pull and install pre-release ``devel`` branch: .. code:: sh pip install "git+https://github.com/tqdm/tqdm.git@devel#egg=tqdm" Latest Conda release ~~~~~~~~~~~~~~~~~~~~ |Conda-Forge-Status| .. code:: sh conda install -c conda-forge tqdm Latest Snapcraft release ~~~~~~~~~~~~~~~~~~~~~~~~ |Snapcraft| There are 3 channels to choose from: .. code:: sh snap install tqdm # implies --stable, i.e. latest tagged release snap install tqdm --candidate # master branch snap install tqdm --edge # devel branch Note that ``snap`` binaries are purely for CLI use (not ``import``-able), and automatically set up ``bash`` tab-completion. Latest Docker release ~~~~~~~~~~~~~~~~~~~~~ |Docker| .. code:: sh docker pull tqdm/tqdm docker run -i --rm tqdm/tqdm --help Other ~~~~~ There are other (unofficial) places where ``tqdm`` may be downloaded, particularly for CLI use: |Repology| .. |Repology| image:: https://repology.org/badge/tiny-repos/python:tqdm.svg :target: https://repology.org/project/python:tqdm/versions Changelog --------- The list of all changes is available either on GitHub's Releases: |GitHub-Status|, on the `wiki <https://github.com/tqdm/tqdm/wiki/Releases>`__, or on the `website <https://tqdm.github.io/releases>`__. Usage ----- ``tqdm`` is very versatile and can be used in a number of ways. The three main ones are given below. Iterable-based ~~~~~~~~~~~~~~ Wrap ``tqdm()`` around any iterable: .. code:: python from tqdm import tqdm from time import sleep text = "" for char in tqdm(["a", "b", "c", "d"]): sleep(0.25) text = text + char ``trange(i)`` is a special optimised instance of ``tqdm(range(i))``: .. code:: python from tqdm import trange for i in trange(100): sleep(0.01) Instantiation outside of the loop allows for manual control over ``tqdm()``: .. code:: python pbar = tqdm(["a", "b", "c", "d"]) for char in pbar: sleep(0.25) pbar.set_description("Processing %s" % char) Manual ~~~~~~ Manual control of ``tqdm()`` updates using a ``with`` statement: .. code:: python with tqdm(total=100) as pbar: for i in range(10): sleep(0.1) pbar.update(10) If the optional variable ``total`` (or an iterable with ``len()``) is provided, predictive stats are displayed. ``with`` is also optional (you can just assign ``tqdm()`` to a variable, but in this case don't forget to ``del`` or ``close()`` at the end: .. code:: python pbar = tqdm(total=100) for i in range(10): sleep(0.1) pbar.update(10
Release History
| Version | Changes | Urgency | Date |
|---|---|---|---|
| 4.67.3 | Imported from PyPI (4.67.3) | Low | 4/21/2026 |
| v4.67.3 | - fix py3.7 dependencies (#1706 <- #1705) | Low | 2/3/2026 |
| v4.67.2 | - support `pandas>=3` (#1703 <- #1701, #1650, #1700) - fix `format_interval` for negative numbers (#1703) - misc linting - framework updates (#1704) + bump CI workflow & `pre-commit` dependencies + add `pyupgrade` + add py3.13 support + fix py3.7 tests + update `setuptools-scm` usage + support auto-dedented docstrings when building docs in py3.13 - tests: relax flaky benchmarks | Low | 1/30/2026 |
| v4.67.1 | - fix `gui` (`matplotlib` syntax) (#1629) - misc test & framework updates - bump `pytest-asyncio` (#1630) - fix `codecov` rate limit - fix pybuild - sync dependencies | Low | 11/27/2024 |
| v4.67.0 | - `contrib.discord`: replace `disco-py` with `requests` (#1536) | Low | 11/6/2024 |
| v4.66.6 | - cli: zip-safe `--manpath`, `--comppath` (#1627) - misc framework updates (#1627) + fix `pytest` `DeprecationWarning` + fix `snapcraft` build + fix `nbval` `DeprecationWarning` + update & tidy workflows + bump pre-commit + docs: update URLs | Low | 10/28/2024 |
| v4.66.5 | - support `ncols` auto-detection on FreeBSD (#1602 <- https://github.com/casperdcl/git-fame/issues/98) - fix Python 3.13 CLI (#1594 <- #1585) - fix Python 3.13 tests (#1595 <- https://github.com/python/cpython/issues/117536#issuecomment-2036883124) - misc framework updates (#1602) + add official Python 3.12 support + bump deps (https://github.com/NiklasRosenstein/pydoc-markdown/issues/329, https://github.com/tikitu/jsmin/pull/44) | Low | 8/3/2024 |
| v4.66.4 | - `rich`: fix completion (#1395 <- #1306) - minor framework updates & code tidy (#1578) | Low | 5/2/2024 |
| v4.66.3 | - `cli`: `eval` safety (fixes CVE-2024-34062, GHSA-g7vv-2v7x-gj9p) | Low | 5/2/2024 |
| v4.66.2 | - `pandas`: add `DataFrame.progress_map` (#1549) - `notebook`: fix HTML padding (#1506) - `keras`: fix resuming training when `verbose>=2` (#1508) - fix `format_num` negative fractions missing leading zero (#1548) - fix Python 3.12 `DeprecationWarning` on `import` (#1519) - linting: use f-strings (#1549) - update tests (#1549) + fix `pandas` warnings + fix `asv` (https://github.com/airspeed-velocity/asv/issues/1323) + fix macos `notebook` docstring indentation - CI: bump actions | Low | 2/10/2024 |
| v4.66.1 | - fix `utils.envwrap` types (#1493 <- #1491, #1320 <- #966, #1319) + e.g. cloudwatch & kubernetes workaround: `export TQDM_POSITION=-1` - drop mentions of unsupported Python versions | Low | 8/10/2023 |
| v4.66.0 | - environment variables to override defaults (`TQDM_*`) (#1491 <- #1061, #950 <- #614, #1318, #619, #612, #370) + e.g. in CI jobs, `export TQDM_MININTERVAL=5` to avoid log spam + add tests & docs for `tqdm.utils.envwrap` - fix & update CLI completion - fix & update API docs - minor code tidy: replace `os.path` => `pathlib.Path` - fix docs image hosting - release with CI bot account again (https://github.com/cli/cli/issues/6680) | Low | 8/9/2023 |
| v4.65.2 | - exclude `examples` from distributed wheel (#1492) | Low | 8/8/2023 |
| v4.65.1 | - migrate `setup.{cfg,py}` => `pyproject.toml` (#1490) + fix `asv` benchmarks + update docs - fix snap build (#1490) - fix & update tests (#1490) + fix flaky notebook tests + bump `pre-commit` + bump workflow actions | Low | 8/8/2023 |
| v4.65.0 | - add Python 3.11 and drop Python 3.6 support (#1439, #1419, #502 <- #720, #620) - misc code & docs tidy - fix & update CI workflows & tests | Low | 3/3/2023 |
| v4.64.1 | - support `ipywidgets>=8` (#1366, #1361 <- #1310, #1359, #1360, #1364) + fix jupyter lab display + update notebook tests | Low | 9/3/2022 |
| v4.64.0 | - add `contrib.slack` (#1313) | Low | 4/4/2022 |
| v4.63.2 | - `rich`: expose `options` kwargs (#1282) - `autonotebook`: re-enable VSCode (#1309) - misc docs typos (#1301, #1299) - update dev dependencies (#1311) | Low | 4/4/2022 |
| v4.63.1 | - fix stderr/stdout missing `flush()` (#1248 <- #1177) - misc speed improvements/optimisations | Low | 3/23/2022 |
| v4.63.0 | - add `__reversed__()` - add efficient `__contains__()` - improve CLI startup time (replace `pkg_resources` => `importlib`) - `tqdm.autonotebook` warning & `std` fallback on missing `ipywidgets` (#1218 <- #1082, #1217) - warn on positional CLI arguments - misc build/test framework updates + enable `py3.10` tests + add `conda` dependencies + update pre-commit hooks + fix `pytest` config (`nbval`, `asyncio`) + fix dependencies & tests + fix site deployment | Low | 2/28/2022 |
| v4.62.3 | - fix minor typo (#1246) - minor example fix (#1246) - misc tidying & refactoring - misc build/dev framework updates + update dependencies + update linters + update docs deployment branches - misc test/ci updates + test forks + tidy OS & Python version tests + bump primary python version 3.7 => 3.8 + beta py3.10 testing + fix py2.7 tests + better timeout handling | Low | 9/20/2021 |
| v4.62.2 | - fix notebook memory leak (#1216) - fix `contrib.concurrent` with generators (#1233 <- #1231) | Low | 8/23/2021 |
| v4.62.1 | - `contrib.logging`: inherit existing handler output stream (#1191) - fix `PermissionError` by using `weakref` in `DisableOnWriteError` (#1207) - fix `contrib.telegram` creation rate limit handling (#1223, #1221 <- #1220, #1076) - tests: fix py27 `keras` dependencies (#1222) - misc tidy: use relative imports (#1222) - minor documentation updates (#1222) | Low | 8/14/2021 |
| v4.62.0 | - `asyncio.gather` API consistency with stdlib (#1212) - fix shutdown exception (#1209 <- #1198) - misc build framework updates (#1209) - add [GH Sponsors](https://github.com/sponsors/tqdm/dashboard/tiers?frequency=one-time) & [merch](https://tqdm.github.io/merch) links | Low | 7/30/2021 |
| v4.61.2 | - install `colorama` on Windows (#1139, #454) - add telegram support for `leave=False` (#1189) - support `pandas==1.3.0` (#1199) - fix `keras` potential `AttributeError` (#1184 <- #1183) - fix py3.10 `asyncio` tests (#1176) - flush `stdout`/`err` before first render (#1177) - misc minor build & test framework updates (#1180) | Low | 7/16/2021 |
| v4.61.1 | - fix `utils._screen_shape_linux()` sometimes raising `ValueError` (#1174) - minor build/CI framework updates (#1175) - minor documentation updates - fix typo (#1178) - link to [merch](https://tqdm.github.io/merch)! :billed_cap: :shirt: | Low | 6/12/2021 |
| v4.61.0 | - `keras` support for `initial_epoch` (#1150 <- #1138) - misc documentation updates + update & shorten URLs (#1163) + fix typos (#1162) - fix & update tests (#1163) - minor framework updates (#1163) | Low | 5/24/2021 |
| v4.60.0 | - add `contrib.logging` helpers for redirecting to `tqdm.write()` (#1155 <- #786) - support `delay` in `notebook` (#1142) - fix `contrib.tmap`, `tzip` not using `tqdm_class` (#1148) - add `notebook` tests (#1143) - updates & misc minor fixes for documentation | Low | 4/6/2021 |
| v4.59.0 | - add `tqdm.dask.TqdmCallback` (#1079, #279 <- #278) - add `asyncio.gather()` (#1136) - add basic support for `length_hint` (#1068) - add & update tests - misc documentation updates (#1132) + update contributing guide + update URLs + bash completion: add missing `--delay` - misc code tidy - add `[notebook]` extra (#1135) | Low | 3/5/2021 |
| v4.58.0 | - add start `delay` in seconds (#836 <- #1069, #704) - add tests - misc code tidy (#1130) - misc documentation updates | Low | 2/25/2021 |
| v4.57.0 | - add line buffering for `DummyTqdmFile` (#960) - fix & update demo notebook (#1127) - fix py3 urllib examples (#1127) - suppress deprecated `pandas` warnings (#824, #1094) - misc framework updates - misc tests updates - misc code tidy | Low | 2/18/2021 |
| v4.56.2 | - fix attribute errors when disabled (#1126) + `reset()` (#1125) + `unpause()` - add tests | Low | 2/10/2021 |
| v4.56.1 | - fix `repr()` & `format_dict` when disabled (#1113 <- #624) - rename `__repr__()` => `__str__()` - minor documentation updatesο»Ώ (#1113) + fix Binder demo notebook (#1119) + remove explicit Dockerfile + move some images to external repo - add & update tests | Low | 2/9/2021 |
| v4.56.0 | - add `tqdm.tk` (#1006) - add `tqdm.rich` - minor formatting improvements for `tqdm.gui` - fix `display()` inheritance/override - add tests - add documentation | Low | 1/11/2021 |
| v4.55.2 | - update tests (#1108) + make pre-commit `pytest` quicker + switch pre-commit from `make` to `python` + add and update (auto) formatters & CI (#1108, #1093) - update contributing guidelines (#1108) + fix formatting + test dependencies (#1109) - update `.gitignore` - fix (auto & manual) formatting - fix minor detected bugs - misc build/CI framework upgrades | Low | 1/9/2021 |
| v4.55.1 | - fix `(Rolling|Expanding).progress_apply()` on `pandas==1.2.0` (#1106) - minor documentation updates | Low | 1/2/2021 |
| v4.55.0 | - fix ASCII notebook export (#937, #1035, #1098) - fix notebook gui-mode extra spaces (#433, #479, #550, #935) - better ETA for early iterations (#1101) - better ETA for wildly varying iteration rates (#1102) - update submodule inheritance + `tqdm.gui` + `tqdm.notebook` + `tqdm.contrib.telegram` + `tqdm.contrib.discord` - documentation updates - misc code optimisations - add tests - framework updates + build + CI & test - misc code linting/formatting | Low | 12/25/2020 |
| v4.54.1 | - drop `py3.4` (no longer tested) (#1091) - misc CI updates (#1091) + update `snap` build & deploy method + bot releases | Low | 12/5/2020 |
| v4.54.0 | - get rid of `get_new` (#1085 <- #1084, #509) - minor CI framework optimisations | Low | 11/27/2020 |
| v4.53.0 | - provide `get_new()` helper for mixed subclasses in nested mode (#509) - fix nested `asyncio` (#1074) + document async `break` hazard - add tests - drop py2.6/3.2/3.3 and distutils (no longer tested) + drop py2.6 (#502 <- #620, #127) + drop `distutils` in favour of `setuptools`/`setup.cfg` (#723, #721) - CI framework overhaul + drop appveyor (Windows already tested by GHA) + skip `devel` PRs + automate linting comments on failure - use `setuptools_scm` (#722) + fix & u | Low | 11/21/2020 |
| v4.52.0 | - allow delaying `display()` to a different notebook cell (#1059 <- #909, #954) + add `notebook` argument `display=True` (use `display=False` with `display(tqdm_object.container)`) + add `keras.TqdmCallback` support for initialiser arguments (use `display=False` with `tqdm_callback_object.display()`) (#1059 <- #1065) + add documentation - add CI on windows (#507) - enable CI on OSX - migrate CI Travis => GHA + add tests for MacOS & Windows + add tests for py3.9 (#1073) + upd | Low | 11/16/2020 |
| v4.51.0 | - add `{eta}` datetime `bar_format` argument (#1055 <- #1051) + e.g. `bar_format='{l_bar}{bar}| {n_fmt}/{total_fmt} [{rate_fmt} ETA:{eta:%y-%m-%d %H:%M}{postfix}]'` - fix py3 CLI `--update` & `--update_to` - replace `nosetests` with `pytest` (#1052, #1045) - add & update tests | Low | 10/25/2020 |
| v4.50.2 | - fixed `platform.system()` causing `fork()` warnings (#691) - fixed `contrib.concurrent.process_map` pickling error with `threading.RLock` (#920) - updated documentation & examples - updated CI framework - updated tests - misc code tidy | Low | 10/8/2020 |
| v4.50.1 | - fix multiprocessing lock creation leak (#982, #936, #759) + fixes #617 which introduced this bug (v4.29.0, released 2019-01-06, undiagnosed until now) where multiple threads could concurrently create and append process locks to a global list, then try to release them without first acquiring :imp: - major test overhaul: fix, update, and speed up - misc CI framework updates - code linting - minor documentation tidy | Low | 10/7/2020 |
| v4.50.0 | - add bar `colour` option (#1040 <- #450) + for `notebook` as well as `std`/CLI + plain text as well as hex (e.g. 'green' or '#00ff00') - `notebook` improvements (#1032 <- #1031) + split bar description into separate widget + improve `reset()` (handle width and colour) - fix exceptions when `file` is closed (#1041, #1036 <- #1033) - add & update tests - minor documentation updates - move and configure issue/pr templates | Low | 9/28/2020 |
| v4.49.0 | - CLI: add `--tee` (#1014 <- #1013) - CLI: add `--update` and `--update_to` (#996 <- #975) - CLI: add `--null` (#996) - CLI: accept `-` instead of `_` in options (e.g. `--update-to`) - make `update()` return `True` on `display` to ease efficient use of custom callbacks (#845) - fix `py>=3` CLI `--delim` encoding error - fix `py>=3.5` version detection in `tqdm.auto` (#1029 <- #1028) - fix final ETA when using `initial` (#1021 <- #689) - update documentation + add & update custom callb | Low | 9/12/2020 |
| v4.48.2 | - fix `notebook` formatting | Low | 8/3/2020 |
| v4.48.1 | - fix ANSI escape codes breaking `tqdm.write` (#692, #777) - fix long-lived strongref (#1007, https://bugs.python.org/issue39093) - fix cli `--version` crash on missing `git/refs/heads` (#635) - fix `contrib.tenumerate` ignoring `total` (#1017) - fix potential deep => shallow `kwargs` copy issues - improve `notebook` display for unknown `total` (#1015) - make `asyncio` inherit from `std` rather than `auto` - make `auto` multi-inherit from `autonotebook`, `asyncio` on Python3.5+ - misc do | Low | 8/3/2020 |
| v4.48.0 | - add `tqdm.asyncio` (#1004, #772, #91 <- #65) + supports async iterables (`async for row in tqdm(iterable)`) + supports iterables + supports `coroutine.send` (`tqdm(coroutine).send`) + add `as_completed` wrapper (`for f in tqdm.as_completed(fs)`) - reduce `contrib.discord` logging verbosity - fix potential `pandas()` modifying `**kwargs` bug - update documentation + add missing inline docstrings + update contributing notes + update readme + add to `examples/` folder | Low | 7/16/2020 |
| v4.47.0 | - add `contrib.discord` (similar to `contrib.telegram`) (#976) - add `contrib.bells` to auto-enable all extras - add `contrib.utils_worker` for common slow tasks (e.g. web I/O) + fix lazy large memory usage & discard unsent messages (unprocessed tasks) - fix slow notebook imports (#955 <- #709) - fix `gui` `TypeError` on unknown `len()` (#971) - misc documentation/error message updates + more succinct ImportError on missing `ipywidgets` (#872) + fix broken/deprecated link (#981) | Low | 6/28/2020 |
| v4.46.1 | - fix missing `sys.setcheckinterval` in py3.9 (#978) - fix `keras.TqdmCallback` compatibility with `tensorflow==2.2.0` (#979) - update documentation + correct `contrib.concurrent` correct `max_workers` (#977) + drop prominent mention of `xrange` (#965) - minor linting | Low | 6/3/2020 |