Python tqdm Nested and Manual Progress Bars

python tqdm nested and manual progress bars requires a clear understanding of the core syntax, runtime behavior, and practical implementation patterns demonstrated in the examples below.

Python's tqdm library supports nested and manual progress bars, two features that cover workloads a single bar cannot handle. Nested bars track loops inside loops; manual bars advance by explicit update calls when work does not map onto an iterable. Both use the same API, and understanding how they interact keeps terminal output readable instead of a jumble of overlapping lines.

How tqdm Positions Nested Progress Bars

tqdm tracks the current cursor position and assigns each new bar the next available line. When you create a tqdm instance inside another, the library detects the nesting and stacks the bars vertically instead of overwriting the outer bar. The simplest form is two nested loops:

from tqdm import tqdm
import time

for epoch in tqdm(range(5), desc="Epoch"):
    for batch in tqdm(range(200), desc="Batch"):
        time.sleep(0.001)

The outer bar occupies the first line; the inner bar appears below it. When the inner loop finishes, the outer bar continues updating on its own line. This automatic behavior is enough for straightforward nesting, but it relies on the bars being created in the same thread and in the expected order.

Controlling Bar Layout with the Position Parameter

Automatic positioning breaks down when bars are created in separate scopes or when you need a bar to stay fixed while another moves. The position parameter gives explicit control over the line each bar uses.

from tqdm import tqdm
import time

outer = tqdm(range(5), desc="Outer", position=0)
for _ in outer:
    inner = tqdm(range(100), desc="Inner", position=1, leave=False)
    for _ in inner:
        time.sleep(0.001)
    inner.close()

position is zero-based. Two bars with the same position overwrite each other, so keep positions unique within the same terminal region. leave=False removes the inner bar after completion, which keeps the terminal from accumulating finished bars. The outer bar, with the default leave=True, stays visible after the loop ends, which is useful when you want the final result to remain on screen.

Manual Progress Bar Updates Without an Iterable

Not every workload is a for loop over a known iterable. When you process a stream, download a file, or consume a generator whose length is unknown, create a tqdm instance with a total and advance it manually with update(n).

from tqdm import tqdm

total_bytes = 1024 * 1024
pbar = tqdm(total=total_bytes, unit="B", unit_scale=True, desc="Download")

received = 0
while received < total_bytes:
    chunk = stream.read(4096)  # stream is a file-like object
    received += len(chunk)
    pbar.update(len(chunk))

pbar.close()

update(n) increments the current count by n. The bar reaches 100% when the accumulated count equals total. If total is unknown, omit it; tqdm then shows only the count and elapsed time instead of a percentage. You can still call update(1) for each processed item, and the bar will display the running count without a completion target.

Combining Nested and Manual Control

The two features combine naturally: an outer loop over files with automatic iteration, and an inner manual bar that tracks bytes read per file.

from tqdm import tqdm

for file in tqdm(files, desc="Files"):
    pbar = tqdm(total=file.size, unit="B", unit_scale=True,
                desc=file.name, leave=False)
    offset = 0
    while offset < file.size:
        chunk = read_chunk(file, offset)
        offset += len(chunk)
        pbar.update(len(chunk))
    pbar.close()

The inner bar is created inside the outer loop, so tqdm positions it below the outer bar automatically. leave=False prevents a finished bar from remaining for every file, which matters when the file list is long. Setting desc per file keeps the output readable because the bar label changes with each file.

Handling Bar Overlap and Refresh Conflicts

The most common failure mode is two bars sharing the same position. This happens when a bar is created in a helper function that runs while another bar is active, or when multiple threads update the same bar. tqdm does not synchronize bars across threads; each instance refreshes independently, and concurrent writes can interleave and corrupt the display.

Assign a unique position to every concurrent bar, and use leave=False for short-lived inner bars. When the automatic nesting detection cannot infer the correct line, create manual bars with explicit position values. In Jupyter notebooks, the terminal layout model does not apply; use tqdm.notebook or tqdm.auto instead, which render bars as HTML widgets and handle nesting differently.

Performance Considerations for Frequent Updates

Every update() call carries Python-level overhead even when tqdm decides not to redraw. tqdm throttles redraws with mininterval (default 0.1 seconds) and miniters (default 10 iterations), so a tight loop calling update(1) a million times will not redraw a million times. The remaining cost is the per-call bookkeeping, which is small but not free.

For very hot loops, raise miniters or call update() in larger increments:

pbar = tqdm(total=total, mininterval=0.5, miniters=1000)

For nested bars, the overhead doubles because both the outer and inner bar process every update. If the inner loop runs millions of iterations, update the inner bar every N items instead of every item, and let the outer bar advance once per inner loop completion. This keeps the display responsive without paying the per-call cost on every iteration.

Choosing Between Nested and Manual Approaches

Use nested bars when you have two or more loops and you want to see progress at every level. Use manual bars when the work is not a loop over an iterable, or when you want to control exactly when the bar advances.

The two approaches are not mutually exclusive. A common pattern is an automatic outer loop with a manual inner bar, as shown earlier. The decision comes down to the progress unit. When the unit is a countable item, automatic iteration is simpler and less error-prone. When the unit is a measured quantity such as bytes or records accumulated over time, manual update() is the correct tool because it lets you advance the bar by the exact amount of work completed.