tqdm

tqdm (read taqadum, تقدّم) means "progress" in arabic.

Instantly make your loops show a progress meter - just wrap any iterable with "tqdm(iterable)", and you're done!

from tqdm import tqdm
for i in tqdm(range(16)):
    ...

Here's what the output looks like:

76%|████████████████████ | 7641/10000 [00:34<00:10, 222.22 it/s]

You can also use trange(N) as a shortcut for tqdm(xrange(N))

Overhead is low -- about 60ns per iteration (80ns with gui=True). By comparison, our esteemed competition ProgressBar has an 800ns/iter overhead. It's a matter of taste, but we also like to think our version is much more visually appealing.

Installation

Latest pypi stable release

pip install tqdm

Latest development release on github

Pull and install in the current directory:

pip install -e git+https://github.com/tqdm/tqdm.git@master#egg=tqdm

Documentation

class tqdm:
    """
    Decorate an iterable object, returning an iterator which acts exactly
    like the orignal iterable, but prints a dynamically updating
    progressbar every time a value is requested.
    """
    def __init__(self, iterable=None, desc=None, total=None, leave=False,
                 file=sys.stderr, ncols=None, mininterval=0.1,
                 miniters=None, ascii=None, disable=False,
                 unit='it', unit_scale=False, gui=False):
        """
        Parameters
        ----------
        iterable  : iterable, optional
            Iterable to decorate with a progressbar.
            Leave blank [default: None] to manually manage the updates.
        desc  : str, optional
            Prefix for the progressbar [default: None].
        total  : int, optional
            The number of expected iterations. If not given, len(iterable) is
            used if possible. As a last resort, only basic progress
            statistics are displayed (no ETA, no progressbar). If `gui` is
            True and this parameter needs subsequent updating, specify an
            initial arbitrary large positive integer, e.g. int(9e9).
        leave  : bool, optional
            If [default: False], removes all traces of the progressbar
            upon termination of iteration.
        file  : `io.TextIOWrapper` or `io.StringIO`, optional
            Specifies where to output the progress messages
            [default: sys.stderr]. Uses `file.write(str)` and `file.flush()`
            methods.
        ncols  : int, optional
            The width of the entire output message. If specified, dynamically
            resizes the progressbar to stay within this bound
            [default: None]. The fallback is a meter width of 10 and no
            limit for the counter and statistics. If 0, will not print any
            meter (only stats).
        mininterval  : float, optional
            Minimum progress update interval, in seconds [default: 0.1].
        miniters  : int, optional
            Minimum progress update interval, in iterations [default: None].
            If specified, will set `mininterval` to 0.
        ascii  : bool, optional
            If [default: None] or false, use unicode (▏▎▋█ █) to fill
            the meter. The fallback is to use ASCII characters `1-9 #`.
        disable : bool
            Whether to disable the entire progressbar wrapper [default: False].
        unit  : str, optional
            String that will be used to define the unit of each iteration
            [default: 'it'].
        unit_scale  : bool, optional
            If set, the number of iterations will be reduced/scaled
            automatically and a metric prefix following the
            International System of Units standard will be added
            (kilo, mega, etc.) [default: False].
        gui  : bool, optional
            If set, will attempt to use matplotlib animations for a
            graphical output [default: false].

        Returns
        -------
        out  : decorated iterator.
        """

    def update(self, n=1):
        """
        Manually update the progress bar, useful for streams
        such as reading files.
        E.g.:
        >>> 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 be called in such a way that `filesize` will be
        exactly reached and printed.

        Parameters
        ----------
        n  : int
            Increment to add to the internal counter of iterations
            [default: 1].
        """

    def close(self):
        """
        Cleanup and (if leave=False) close the progressbar.
        """

def trange(*args, **kwargs):
    """
    A shortcut for tqdm(xrange(*args), **kwargs).
    On Python3+ range is used instead of xrange.
    """

Examples and Advanced Usage

See the examples folder.

tqdm can easily support callbacks/hooks and manual updates. Here's an example with urllib:

urllib.urlretrieve documentation

[...]
If present, the hook function will be called once on establishment of the network connection and once after each block read thereafter. The hook will be passed three arguments; a count of blocks transferred so far, a block size in bytes, and the total size of the file.
[...]

import tqdm
import urllib

def my_hook(**kwargs):
    t = tqdm.tqdm(**kwargs)
    last_b = [0]

    def inner(b=1, bsize=1, tsize=None, close=False):
        if close:
            t.close()
            return
        t.total = tsize
        t.update((b - last_b[0]) * bsize) # manually update the progressbar
        last_b[0] = b
    return inner

eg_link = 'http://www.doc.ic.ac.uk/~cod11/matryoshka.zip'
eg_hook = my_hook(unit='B', unit_scale=True, leave=True, miniters=1,
                  desc=eg_link.split('/')[-1]) # all optional kwargs
urllib.urlretrieve(eg_link,
                   filename='/dev/null', reporthook=eg_hook, data=None)
eg_hook(close=True)

It is recommend to use miniters=1 whenever there is potentially large differences in iteration speed (e.g. downloading a file over a patchy connection).

Contributions

To run the testing suite please make sure tox (http://tox.testrun.org/) is installed, then type tox from the command line.

Alternatively if you don't want to use tox, a Makefile is provided with the following command:

$ make flake8
$ make test
$ make coverage

See the CONTRIBUTE file for more information.

License

MIT LICENSE.

Authors

• Noam Yorav-Raphael (noamraph, Original Author)
• Ivan Ivanov (obiwanus)
• Mikhail Korobov (kmike)
• Hadrien Mary (hadim)
• Casper da Costa-Luis (casperdcl)
• Stephen Larroque (lrq3000)