Introduction

tqdm is a progress bar library designed to be fast and extensible. It is written in Python, though ports in other languages are available. tqdm means progress in Arabic (taqadum [@tqdm-ar]) and is an abbreviation for I love you so much in Spanish (te quiero demasiado [@tqdm-es]).

It is a common programming problem to have iterative operations where progress monitoring is desirable or advantageous. Including statements within a for loop to print out the current iteration number is a common strategy. However, there are many improvements which could be made in such a scenario:

• preventing excessive printing, such as only displaying every $n$^th^ iteration;
• displaying iteration rate;
• displaying elapsed and estimated completion times, and
• showing all of the above on one continuously updating line.

Addressing all these issues may well take up more developer time and effort than the rest of the content of the loop. Any changes to iteration rates or attempts to re-use the printing logic in a different loop may well result in suboptimal display rates -- displaying every $n$^th^ iteration may be too (in)frequent -- requiring manual adjustment of $n$ to fix.

tqdm addresses all of these problems once and for all, taking advantage of Pythonic patterns to make it a trivial task to add visually appealing, customisable progress bars without any significant performance degradation even in the most demanding of scenarios.

tqdm is intended to be used in frontends (giving end users a visual indication of progress of computations or data transfer). It is also useful for developers for debugging purposes, both as a profiling tool and also as a way of displaying logging information of an iterative task (such as error during training of machine learning algorithms). Due to its ease of use, the library is also an ideal candidate for inclusion in Python educational courses. For general (not necessarily Python) purposes, the command-line interface (CLI) mode further presents a useful tool for CLI users and system administrators monitoring data flow through pipes.

Features

Exhaustive documentation may be found on the project's home page.

The two basic use cases are within Python code and within a CLI:

Python Iterable Wrapper

tqdm's primary (and original) use is as a wrapper around Python iterables. A simple case would be:

from tqdm import tqdm
from time import sleep
for i in tqdm(range(100)):
    sleep(0.1)
100%|#########################################| 100/100 [00:10<00:00,  9.95it/s]

Supported features include:

• Display customisation via arguments such as desc, postfix and bar_format
• Automatic limiting of display updates to avoid slowing down due to excessive iteration rates [@stdout]
• Automatic detection of console width to fill the display
• Automatic use of Unicode to render smooth-filling progress bars on supported terminals
• Support for custom rendering frontends, including:
  • Command-line interface
  • Jupyter HTML notebooks
  • matplotlib
• Support for custom hooks/callbacks, including:
  • pandas
  • keras [@keras]

Command-line Interface (CLI)

A CLI is also provided, where tqdm may be used a pipe:

 # count lines of text in all *.txt files
$ cat *.txt | wc -l
1075075
 # same but with continuously updating progress information
$ cat *.txt | python3 -m tqdm --unit loc --unit_scale | wc -l
1.08Mloc [00:07, 142kloc/s]
 # same if `total` is known
$ cat *.txt | python3 -m tqdm --unit loc --unit_scale --total 1075075 | wc -l
100%|#####################################| 1.08/1.08M [00:07<00:00,  142kloc/s]
1075075

Availability

The package supports both Python versions 2 and 3, and is available for download via conda [@conda], pip [@pypi], snap [@snapcraft], docker [@docker], and Zenodo [@zenodo]. Web-based Jupyter interactive demonstrations are also available [@notebooks;@binder]

Unit tests are run at least weekly on cloud-based continuous integration [@travis], with code style and security issues checked on Codacy [@code-review]. Coverage is reported on Coveralls and Codecov, and performance is monitored against regression [@asv].

Impact

As of January 2019, tqdm has accumulated over 20 million downloads [@pypi-downloads], and 315 thousand code inclusions [@tqdm-results]. Dependants of tqdm include 23 thousand repositories [@tqdm-dependents] and 7 thousand libraries [@lib-io]. tqdm has a SourceRank of 22 [@sourcerank], placing it in the world's top 20 Python packages as of early 2019 [@sourcerank-descending].

The source code of tqdm is hosted on GitHub, where it has received over 9 thousand stars [@stars;@stars-hist], and was top trending repository during a period in December 2015 [@trend-hist]. The documentation has received over 500 thousand hits [@hits], with highest rates during weekdays. Historical reading rates have also trended upwards at the end of holiday periods. This implies widespread use in commercial and academic settings. OpenHub valuates the work according to the constructive cost model (COCOMO) as being worth approximately $50,000.

The library has also been used in several textbooks [@miller;@boxel;@nandy] and peer-reviewed scientific publications [@stein;@cook;@madhikar;@palmer;@knight;@moriwaki;@jackson]. The tqdm wiki also lists other references in public media.

Licence

tqdm's source code is OSS, and all versions are archived at the DOI 10.5281/zenodo.595120. The primary maintainer Casper da Costa-Luis releases contributions under the terms of the MPLv2.0, while all other contributions are released under the terms of the MIT licence [@licence].

References