tqdm
Fast, Extensible Progress Meter
Downloads: 0 (30 days)
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)
pbar.close()
Module
~~~~~~
Perhaps the most wonderful use of ``tqdm`` is in a script or on the command
line. Simply inserting ``tqdm`` (or ``python -m tqdm``) between pipes will pass
through all ``stdin`` to ``stdout`` while printing progress to ``stderr``.
The example below demonstrate counting the number of lines in all Python files
in the current directory, with timing information included.
.. code:: sh
$ time find . -name '*.py' -type f -exec cat \{} \; | wc -l
857365
real 0m3.458s
user 0m0.274s
sys 0m3.325s
$ time find . -name '*.py' -type f -exec cat \{} \; | tqdm | wc -l
857366it [00:03, 246471.31it/s]
857365
real 0m3.585s
user 0m0.862s
sys 0m3.358s
Note that the usual arguments for ``tqdm`` can also be specified.
.. code:: sh
$ find . -name '*.py' -type f -exec cat \{} \; |
tqdm --unit loc --unit_scale --total 857366 >> /dev/null
100%|█████████████████████████████████| 857K/857K [00:04<00:00, 246Kloc/s]
Backing up a large directory?
.. code:: sh
$ tar -zcf - docs/ | tqdm --bytes --total `du -sb docs/ | cut -f1` \
> backup.tgz
44%|██████████████▊ | 153M/352M [00:14<00:18, 11.0MB/s]
This can be beautified further:
.. code:: sh
$ BYTES=$(du -sb docs/ | cut -f1)
$ tar -cf - docs/ \
| tqdm --bytes --total "$BYTES" --desc Processing | gzip \
| tqdm --bytes --total "$BYTES" --desc Compressed --position 1 \
> ~/backup.tgz
Processing: 100%|██████████████████████| 352M/352M [00:14<00:00, 30.2MB/s]
Compressed: 42%|█████████▎ | 148M/352M [00:14<00:19, 10.9MB/s]
Or done on a file level using 7-zip:
.. code:: sh
$ 7z a -bd -r backup.7z docs/ | grep Compressing \
| tqdm --total $(find docs/ -type f | wc -l) --unit files \
| grep -v Compressing
100%|██████████████████████████▉| 15327/15327 [01:00<00:00, 712.96files/s]
Pre-existing CLI programs already outputting basic progress information will
benefit from ``tqdm``'s ``--update`` and ``--update_to`` flags:
.. code:: sh
$ seq 3 0.1 5 | tqdm --total 5 --update_to --null
100%|████████████████████████████████████| 5.0/5 [00:00<00:00, 9673.21it/s]
$ seq 10 | tqdm --update --null # 1 + 2 + ... + 10 = 55 iterations
55it [00:00, 90006.52it/s]
FAQ and Known Issues
--------------------
|GitHub-Issues|
The most common issues relate to excessive output on multiple lines, instead
of a neat one-line progress bar.
- Consoles in general: require support for carriage return (``CR``, ``\r``).
* Some cloud logging consoles which don't support ``\r`` properly
(`cloudwatch <https://github.com/tqdm/tqdm/issues/966>`__,
`K8s <https://github.com/tqdm/tqdm/issues/1319>`__) may benefit from
``export TQDM_POSITION=-1``.
- Nested progress bars:
* Consoles in general: require support for moving cursors up to the
previous line. For example,
`IDLE <https://github.com/tqdm/tqdm/issues/191#issuecomment-230168030>`__,
`ConEmu <https://github.com/tqdm/tqdm/issues/254>`__ and
`PyCharm <https://github.com/tqdm/tqdm/issues/203>`__ (also
`here <https://github.com/tqdm/tqdm/issues/208>`__,
`here <https://github.com/tqdm/tqdm/issues/307>`__, and
`here <https://github.com/tqdm/tqdm/issues/454#issuecomment-335416815>`__)
lack full support.
* Windows: additionally may require the Python module ``colorama``
to ensure nested bars stay within their respective lines.
- Unicode:
* Environments which report that they support unicode will have solid smooth
progressbars. The fallback is an ``ascii``-only bar.
* Windows consoles often only partially support unicode and thus
`often require explicit ascii=True <https://github.com/tqdm/tqdm/issues/454#issuecomment-335416815>`__
(also `here <https://github.com/tqdm/tqdm/issues/499>`__). This is due to
either normal-width unicode characters being incorrectly displayed as
"wide", or some unicode characters not rendering.
- Wrapping generators:
* Generator wrapper functions tend to hide the length of iterables.
``tqdm`` does not.
* Replace ``tqdm(enumerate(...))`` with ``enumerate(tqdm(...))`` or
``tqdm(enumerate(x), total=len(x), ...)``.
The same applies to ``numpy.ndenumerate``.
* Replace ``tqdm(zip(a, b))`` with ``zip(tqdm(a), b)`` or even
``zip(tqdm(a), tqdm(b))``.
* The same applies to ``itertools``.
* Some useful convenience functions can be found under ``tqdm.contrib``.
- `No intermediate output in docker-compose <https://github.com/tqdm/tqdm/issues/771>`__:
use ``docker-compose run`` instead of ``docker-compose up`` and ``tty: true``.
- Overriding defaults via environment variables:
e.g. in CI/cloud jobs, ``export TQDM_MININTERVAL=5`` to avoid log spam.
This override logic is handled by the ``tqdm.utils.envwrap`` decorator
(useful independent of ``tqdm``).
If you come across any other difficulties, browse and file |GitHub