mqdm

progress bars for parallel work

mqdm keeps the familiar tqdm-style loop shape while adding support for parallel workers and nested progress bars. mqdm works seamlessly across processes allowing you to transparently track progress without worrying about the underlying parallelism.

In the spirit of tqdm (taqadum, تقدّم), mqdm stands for "mutaqaddim" (مُتَقَدِّم) which means "the one who progresses" referring to the parallel workers that are advancing the progress. The less ret-con-y name is "multiprocessing tqdm" :)

The basic shape

mqdm wraps an iterable, just like tqdm.

import time

import mqdm


things = [
    "cats",
    "clouds",
    "notes",
    "pigeons",
    "rock",
    "shoelaces",
]

for thing in mqdm.mqdm(things, desc="looking at"):
    for _ in mqdm.mqdm(range(60), desc=lambda _, i: f"{thing} · #{i + 1}"):
        time.sleep(0.02)

The same shape also seamlessly scales to parallel work:

import time
import mqdm


def doing_something(thing):
    """Process a given thing."""
    items = range(len(thing) * 14)
    for _ in mqdm.mqdm(items, desc=lambda _, i: f"{thing} · #{i + 1}"):
        time.sleep(0.01 * len(thing))
    return thing


things = [
    "cats",
    "clouds",
    "notes",
    "pigeons",
    "rock",
    "shoelaces",
    "moss",
    "sparrows",
]

def main():
    # An outer progress bar shows the pool progress.
    # Each worker has its own inner progress bar for the work inside that item.
    mqdm.pool(
        doing_something, 
        things, 
        desc="looking at", 
        n_workers=3)


if __name__ == "__main__":
    main()

Why mqdm?

mqdm gives you:

• tqdm-style progress bars
• automatic nested progress bars across parallel workers
• worker-pool execution with concurrent.futures (processes and threads)
• pretty progress bars and TUI integration, powered by rich
• progress-safe printing and logging across processes

Get Started

For an end-to-end example, start with Examples.

For examples for how to use mqdm, see:

1. Loops
2. Pools
3. Output
4. Patterns

For the full API, see API reference.