< All Topics
Print

TQDM

Progress monitoring can be desirable as it enables developers to predict the total time required to complete a set of tasks. However, it may not be desirable since it can hamper the iteration process’s effectiveness due to the inefficient use of resources, excessive displaying of elapsed and estimated completion times, and iteration rate. 

To overcome these challenges, Casper da Costa-Luis built “tqdm”, a progress bar package focusing on speed and extensibility. With tqdm, developers can monitor progress without compromising the efficiency of the iteration process. It provides a concise and informative progress bar that displays relevant information, such as the percentage of completed tasks and the estimated completion time, without overwhelming the user with excessive details.

Tqdm was written in Python, although ports are available in other languages such as C++, Go, Julia, Node.js, and more. Its name, tqdm, denotes “progress” in Arabic (taqadum) and is the abbreviation for “I love you so much” in Spanish (te quiero demasiado).

This package offers a straightforward and convenient method to incorporate progress bars into code, making it easier for users to work with loops and functions without worrying about the technical details of implementing complex progress monitoring.

Components and Modules

The tqdm package comprises multiple components, each serving a unique purpose, such as extending functionality to other packages or simplifying syntaxis. Here are some of the central and most commonly used modules:

  • tqdm: It is the standard module to create progress bars for loops.
  • trange: It performs similar tasks to Python’s “.range()” function and provides a progress bar. 
  • auto: It automatically detects the working environment and selects the appropriate module, whether you are working with Notebooks or in the terminal.
  • asyncio: This module provides support for showing the progress of asynchronous tasks.
  • notebook: This module provides Jupyter Notebook integration.
  • contrib: It contains experimental modules, which mainly work as extensions for Slack, Discord, Telegram, and more.

In addition, users can easily customize their progress bars with specific colors and descriptions. By default, progress bars are colored black, but when working with nested loops, the bar takes the colors: blue during normal execution, green when a loop is completed, and red if an error or interruption occurs.

Please, refer to the documentation to discover more features and sub-modules.

Tqdm vs. Similar Python Packages

tqdmRichAlive-progress
LicenseMIT licenseMIT licenseMIT license
PurposeFor providing simple and customizable progress bars.For creating rich text and media in the terminal.For providing a highly customizable and flexible progress bar.
DescriptionIt is a Python-based package for adding progress bars in various contexts, including loops and functions.It is a Python-based package for creating rich text and media in the terminal, including a progress bar that allows users to pause, resume, and cancel tasks.It is a Python-based package that provides a variety of progress bar styles, including bars, spinners, and counters.
PerformanceIt is lightweight and easy to use, with a minimalistic design.It is more feature-rich and customizable but can be more resource-intensive and slower than tqdm.It was optimized for speed and efficiency but can be more resource-intensive and slower than tqdm.
Components/Modulestqdm,
trange,
auto,
gui,
tk,
rich,
keras,
dask,
notebook, and
asyncio.
Log, 
Logging Handler, 
Emoji, 
Tables, 
Progress Bars,
Status,
Tree, Columns,
Markdown,
Syntax Highlighting, and
Tracebacks.
Progress bar, 
Spinner, 
Counters
Eta (Expected Time of Arrival),
Comparison of similar packages for adding progress bars into Python code. Data collected in March/2023.
Sources: Tqdm, Rich, and Alive-progress.

Quick Installation Guide

Python 3.7 (and onwards) already has tqdm installed. For conda users, use the following command in the Anaconda prompt to verify that it is in your system.

conda list

It will print a list, and you will be able to see the “tqdm” package. If your system does not contain it, you can install tqdm by running the command:

conda install -c conda-forge tqdm

Look at these tutorials to install Anaconda in Windows and Ubuntu. Alternatively, you can use the pip package manager.

pip install tqdm

Once the installation is complete, you can import the package into your code.

from tqdm import tqdm
from tqdm.notebook import tnrange, tqdm_notebook
The import statement for a tqdm package.

Tqdm Fundamentals

Making a Progress Bar

You can add progress bars to monitor the progress of long-time tasks and provide a better user experience for your program. For example, to control the progress of a simple loop, use the “.tqdm()” function as follows.

#PYNOMIAL - 2023 
# Import Packages time and tqdm
import time
import tqdm
# Create a loop using the .tqdm() function
for i in tqdm.tqdm(range(150)):
    time.sleep(0.1)
#After the loop is finished, print the status
print("done!")

In the example above, the “.tqdm()” function wraps the iteration process, showing a percentage from 0 to 100.

Creating Nested Loops

Tqdm enables users to display progress bars when working with Jupyter Notebooks. For that, it is recommended to employ the “tqdm.notebook” module to achieve optimal performance. However, you can use “tqdm.auto” instead of “tqdm.notebook” if you want to work in both the notebook environment and the terminal.

In the following example, we have added descriptions for nested loops, making it easier to track the progress of each one.

#PYNOMIAL - 2023
# Import Packages time and tqdm
from tqdm.notebook import trange, tqdm
from time import sleep
# Create nested loops using the .trange() and .tqdm() functions
for i in trange(5, desc='1st loop'):
    for j in tqdm(range(50), desc='2nd loop'):
        sleep(0.01)

The “.trange()” function wraps two iteration processes, where each bar represents the tasks’ current status.

Highlights

Project Background

  • Project: TQDM
  • Author: Casper da Costa-Luis
  • Initial Release: 2015
  • Type: Progress Bar Package
  • License: MPLv2.0, MIT
  • Contains: Bar progress 
  • Language: Python
  • GitHub: /tqdm
  • Runs On: Linux, Windows, Mac, FreeBSD, NetBSD, Solaris/SunOS
  • Twitter: –

Main Features

  • Display customization via arguments.
  • The automatic limiting of display updates prevents slowdowns due to excessive iteration rates.
  • It detects the console width to fill the display.
  • It uses Unicode to render smooth-filling progress bars on supported terminals.
  • Offering front-end support enables end-users to track the progress of computations or data transfer.

Prior Knowledge Requirements

Here are a few tips to effectively use this library:

  • Have a basic understanding of the Python programming language.
  • Learn how to navigate the file system and run commands from the terminal or command prompt.
  • Know basic programming concepts such as data structures, loops, functions, and methods.

Community Benchmarks

  • 24,200 Stars
  • 1,200 Forks
  • 99+ Code contributors
  • 119+ releases
  • Source: GitHub

Releases

  • v4.65.0 (3-4-2023): Update and Fixes: e.g., add Python 3.11 and drop Python 3.6 support.
  • v4.64.1 (9-3-2022): Update and Fixes: e.g., fix jupyter lab display.
  • v4.64.0 (4-4-2022): Update and Fixes: e.g., add contrib.slack.
  • v4.63.2 (4-4-2022): Update and Fixes: e.g., update dev dependencies.
  • v4.63.2 (3-23-2022): Update and Fixes: e.g., fix stderr/stdout missing flush()
  • Source: Releases

References

Home page

GitHub

Tqdm: A Fast, Extensible Progress Meter for Python and CLI, Journal of Open Source Software.

Was this article helpful?
0 out of 5 stars
5 Stars 0%
4 Stars 0%
3 Stars 0%
2 Stars 0%
1 Stars 0%
5
Please Share Your Feedback
How Can We Improve This Article?
Table of Contents
Scroll to Top