tqdm: The Tiny Library That Taught Machines Patience

The Watched Pot

This is episode seventeen of What Did I Just Install.

You have stared at a terminal doing nothing. You have watched a cursor blink on an empty line while something, somewhere, processes your data. You do not know if it will take ten seconds or ten hours. You do not know if it has crashed. You do not know if you should go make coffee or restart the whole thing. Every developer has been here. Every data scientist has been here. Every person who has ever trained a machine learning model has sat in this exact chair, watching an empty screen, wondering if the universe has simply stopped.

Now imagine a single line appears. A bar, filling slowly from left to right. A percentage. An estimate. Three minutes and forty two seconds remaining. You exhale. You know it is working. You know when it will finish. You can plan the rest of your afternoon around that number. This is what tqdm does. It tells you where you are. And the distance between not knowing and knowing turns out to be one of the most important gaps in all of software.

The library that fills that gap has no dependencies. It adds roughly sixty nanoseconds of overhead per iteration, which is essentially nothing. It works on every operating system, in every terminal, in Jupyter notebooks, in command line pipes. It wraps any iterable in Python with a single function call. And as of February twenty twenty six, it gets downloaded over three hundred million times per month from PyPI alone.

Three hundred million. Every month. For a progress bar.

What It Actually Does

Before tqdm, you had options, and none of them were good. You could print a counter inside your loop, flooding your terminal with numbers scrolling past too fast to read. You could print a dot every thousand iterations and try to estimate by counting dots. You could write your own progress bar with carriage returns and string formatting, which sounds simple until you account for terminal width, elapsed time calculation, speed estimation, remaining time prediction, nested loops, parallel processing, and the fact that different terminals handle carriage returns differently on different operating systems.

Or you could use one of the existing libraries, like progressbar or progressbar2, which worked but added eight hundred nanoseconds of overhead per iteration. That sounds trivial until your loop runs a billion times. At eight hundred nanoseconds each, you have just added thirteen minutes of pure progress bar overhead to your computation. The thing that was supposed to tell you how long your work would take was itself making your work take longer.

tqdm solved this with what its creator would later describe as obsessive optimization. Sixty nanoseconds per iteration. That is roughly fourteen times faster than the alternative. On a billion iterations, tqdm adds about one minute of overhead. The progress bar displays elapsed time, iterations per second, estimated time remaining, and a visual bar that fills from left to right. It uses smart algorithms to smooth its estimates, avoiding the jumpy predictions that plagued earlier tools. And it does all of this with zero dependencies. Not one. It needs Python and a terminal that supports a carriage return character. That is the entire dependency tree.

The Physicist Who Adopted a Progress Bar

The original tqdm was created in October twenty thirteen by a developer named Noam Yorav-Raphael. It was elegant in its simplicity. Wrap your iterable, get a progress bar. Noam wrote sixteen commits over the life of the original repository, and then, as happens with so many side projects, life moved on. The code sat quietly on GitHub, useful but unchanging.

Around twenty fifteen, a physics student at Imperial College London named Casper da Costa-Luis encountered the same problem every developer encounters. His loops were running and he could not tell when they would finish. He found Noam's tqdm, saw its potential, and did something unusual. Instead of simply using it, he essentially rebuilt it from the ground up while keeping the name, the philosophy, and the core interface intact.

Casper is not your typical open source maintainer. He holds a bachelor of science in physics from Imperial College London, a master of science with distinction in computer science from the same university, and a PhD from King's College London in deep learning for medical imaging. His doctoral thesis focused on PET image reconstruction, the kind of work where you spend days training neural networks to reconstruct three dimensional images of the human body from the faint signals of radioactive tracers. If anyone understood the agony of watching a training loop with no progress indication, it was someone building medical imaging systems.

His client list reads like someone who wanders between worlds. Sony. The World Bank. The Met Office. University College London. The United Kingdom Department of Science, Innovation and Technology. He is a member of the Institute of Electrical and Electronics Engineers, a member of the Institute of Physics, a fellow of the Python Software Foundation. He won bronze awards from the PET and MR imaging community in twenty seventeen and twenty eighteen, and IEEE grants for his work in nuclear science.

And his personal blog is called Too Long, Didn't Read. Which, if you squint, is the spiritual cousin of tqdm itself. A library about not wanting to wait. A blog about not wanting to read.

I do not get paid for this. I did not expect it to be used by anyone.

That sentence captures something essential about how infrastructure software gets built. The people who create the tools that millions depend on rarely set out to create tools that millions depend on. They are scratching an itch. Casper was a physicist who needed to know when his loops would finish. He found a sixteen-commit repository from twenty thirteen and turned it into one of the most downloaded Python packages in the world.

A Name in Two Languages

The name tqdm is one of the more charming etymologies in the Python ecosystem. It comes from the Arabic word taqaddum, spelled taa-qaaf-daal-daal-meem in Arabic script, meaning progress. If you are building a progress bar, naming it after the Arabic word for progress has a pleasing circularity to it. The tool that shows progress is itself named progress.

But there is a second meaning, and it is the one that makes people smile. In Spanish slang, tqdm is also an abbreviation for te quiero demasiado, which translates to I love you too much. A progress bar named both progress and I love you too much. There is something endearing about that duality. A tool born from the practical frustration of not knowing when a loop will finish, carrying the name of a love letter in a language most of its users do not speak.

I always thought it was just a random string of letters. Finding out it means I love you too much in Spanish completely changed how I feel about progress bars.

Noam Yorav-Raphael chose the name for the original project. It stuck through the rewrite, through the reorganization, through the explosive growth. No one ever suggested changing it. In a world of packages named with clinical precision, descriptive hyphens, and aggressive branding, tqdm remains a quiet word from Arabic that most English speakers cannot pronounce on their first try.

From Side Project to Three Hundred Million

The early releases tell the story of someone building in public. Version two point zero arrived in October twenty fifteen, the first documented release under the tqdm organization on GitHub. Version four point zero followed in February twenty sixteen, establishing the architecture that would carry the project for the next decade. Each release added something the community needed. Jupyter notebook integration in twenty eighteen. Keras callbacks for TensorFlow training loops in twenty twenty. Async support for modern Python in the same year. Even a Telegram integration, so you could get your progress bars sent to your phone.

The growth curve is remarkable precisely because there was no growth strategy. No venture capital, no marketing, no developer advocacy team. Just a library that did one thing well, with zero dependencies and negligible overhead, maintained by a physicist working on medical imaging. Word spread the way word spreads for genuinely useful tools. Someone wraps a loop with tqdm, their colleague sees the progress bar, asks what it is, and then wraps their own loops. Multiply this by a decade and you get three hundred million monthly downloads.

In twenty nineteen, Casper formalized the project academically. He published a paper in the Journal of Open Source Software titled tqdm: A Fast, Extensible Progress Meter for Python and CLI. It is unusual for a progress bar to have a peer-reviewed paper, but it reflects how Casper thinks about the work. This is not just a utility. It is a piece of software infrastructure with measurable performance characteristics and design decisions worth documenting.

The project grew while I was staying current with evolving technologies. Jupyter. Docker. Snapcraft. Markdown. GitHub. PyPI. Conda. Each new platform was another integration to build.

Somewhere along the way, someone Casper had never met composed a song about tqdm and published it in an obscure blog comment without telling him. He found it by accident. This is what it means to build something that matters to strangers. Not a thank you email, not a GitHub star. A song, written in gratitude, left in a corner of the internet where the creator might never find it.

The Psychology of Knowing

Let us step back from the code for a moment and think about what a progress bar actually is. It is information about time. It is a promise that the thing you started will eventually finish, and an estimate of when. This sounds trivial. It is not.

Research in human computer interaction has shown repeatedly that perceived wait time is different from actual wait time. A task that takes sixty seconds with a progress bar feels shorter than a task that takes forty seconds without one. The progress bar does not speed anything up. It changes how you experience the wait. It converts anxiety into planning. You stop wondering if the process has crashed and start thinking about what to do when it finishes.

This is why tqdm matters beyond its technical cleverness. It is a user experience tool for the command line, a space where user experience is rarely discussed. Most command line tools are designed by engineers for engineers, and the assumption is that the user will simply wait. tqdm challenged that assumption. It said that even a terminal window deserves to communicate with its user, that even a Python script running in a dark terminal at two in the morning should have the courtesy to tell you how long you have to wait.

The first time I added tqdm to a training loop, nothing about the training changed. But everything about my experience of training changed. I could leave the room. I could sleep. I knew it would be done by morning.

The Dependency Tree That Isn't

Here is where the tqdm story gets quietly remarkable. Open the dependency list for tqdm. It is empty. Zero runtime dependencies. The library needs Python and a terminal that can handle a carriage return. That is the complete list.

In an ecosystem where a typical machine learning project pulls in hundreds of dependencies, where a web framework might require dozens of packages just to start, tqdm requires nothing. This is a deliberate choice, not an accident. Every dependency is a potential point of failure, a security surface, a compatibility constraint. By depending on nothing, tqdm can be depended on by everything.

And it is depended on by everything. Look at any serious Python project in machine learning, data science, or scientific computing. PyTorch uses tqdm. TensorFlow projects use tqdm. Hugging Face Transformers uses tqdm. Pandas uses tqdm. Scikit-learn uses tqdm. The list goes on and on, a cascading tree of dependencies that all point back to a zero-dependency library maintained by a physicist in London.

The architectural decision to remain dependency-free is also what makes tqdm so resilient. In two thousand eighteen, a popular npm package called event-stream was hijacked when its maintainer handed it to a stranger who injected cryptocurrency-stealing malware. The attack spread through dozens of transitive dependencies. In two thousand twenty-two, the maintainer of colors.js sabotaged his own package, breaking thousands of applications overnight. Both attacks exploited the same thing: a chain of dependencies where one compromised link poisons everything downstream. Tqdm has no chain. It has no supply chain to attack. It is a leaf node in the dependency graph, and leaf nodes cannot be compromised through their children because they have no children.

The Aftermath

As of twenty twenty six, tqdm sits at over thirty one thousand GitHub stars and roughly three hundred six million monthly downloads from PyPI. It has been stable on version four for a decade. It runs on Linux, Windows, Mac, FreeBSD, NetBSD, and Solaris. It works in terminals, in Jupyter notebooks, in continuous integration pipelines, and through Telegram bots.

Casper finished his PhD at King's College London in twenty twenty two and has continued maintaining tqdm alongside his work in medical imaging and government technology. He does not get paid for tqdm. There is a GitHub sponsors page, but tqdm is not a company, not a product, not a service. It is a library that one person adopted and turned into infrastructure.

I used this project to stay current with everything. It forced me to learn platforms I would never have touched otherwise. That is the hidden benefit of maintaining popular open source. The world comes to you.

Alternatives exist. Will McGuigan's Rich library offers progress bars as part of a full terminal formatting suite. The alive-progress library adds animations and themes. But tqdm remains the default, the one you reach for without thinking, the one that shows up in every tutorial and every training script. Part of this is inertia. Part of it is that tqdm does exactly what it promises with exactly zero overhead and exactly zero dependencies. Sometimes the first tool that solves a problem well enough becomes the last tool anyone needs.

The licensing tells its own quiet story. Casper chose the Mozilla Public License version two for his contributions, while the original code and other contributions remain under MIT. He thought about it deliberately, opting for a license that requires modifications to be shared while still allowing proprietary use. A physicist's compromise between openness and protection.

Where It Lives on Your Machine

Here is the personal part. If you have ever run a machine learning project, tqdm was there. It is in the requirements for face swapping tools like FaceFusion and DeepFaceLab. It is inside transcription pipelines like Whisper and its derivatives. It is in every computer vision experiment, every fine-tuning script, every data preprocessing notebook you have ever opened. Every time a model downloads its weights, every time a training loop ticks forward, every time a batch of images gets processed, a little progress bar appears on screen, filling from left to right, telling you where you are and how long you have to wait.

Three hundred million downloads a month. Zero dependencies. One maintainer who started as a physics student and never expected anyone to use what he built. A name that means both progress and I love you too much. And sixty nanoseconds per iteration, which is the time it takes light to travel about eighteen meters. In the time it takes tqdm to update your progress bar, a photon has crossed a room.

That feels about right for a library that exists to make waiting bearable. It moves at the speed of light, and all it does is tell you that everything is going to be fine.

Open a terminal and type pip install tqdm. Then open a Python shell. Type from tqdm import tqdm, then for i in tqdm open parenthesis range open parenthesis ten thousand close parenthesis close parenthesis colon pass. Watch the progress bar fill your terminal. Then try adding tqdm dot write open parenthesis quote hello quote close parenthesis inside the loop and see how it prints without breaking the bar. That is the sixty nanosecond overhead Casper engineered. A progress bar that knows how to share the terminal.

That was episode seventeen.