BarFlow

A fast Python progress bar library with a C++ core. Cross-platform — first-class on Windows, macOS, and Linux. Built to beat tqdm, rich.progress, and alive-progress on cold import, per-iteration overhead, peak it/s, memory footprint, tail latency, multi-bar throughput, and first-frame latency — simultaneously.

import barflow

# Fastest: `for _ in progress:` runs at 160+ M it/s — faster than
# a bare `for _ in range(n): pass` because Py_None is immortal.
with barflow.Progress(total=n, desc="Crunching") as p:
    for _ in p:
        do_work()

# When you also need the iterated values:
for x in barflow.track(range(1_000_000), desc="Working"):
    ...

# Event-driven / manual:
with barflow.Progress(total=n, desc="Streaming") as p:
    for chunk in data:
        process(chunk)
        p.advance(len(chunk))

Benchmarks

Numbers below are from benchmarks/bench.py on Windows 11 / Python 3.13 / N = 20,000,000 iterations (5 runs per data point, best wall time for rate measurements, min CPU time for CPU measurements). Baseline bare for _ in range(n): pass is 145.75 M it/s (6.9 ns/iter, 140.6 ms of CPU). Raw output lives in benchmarks/bench_raw.md; methodology and platform notes are in benchmarks/results.md.

Headline

BarFlow wins on every axis — 25–62× faster cold import, zero measurable overhead on its iteration fast path (faster than a bare for _ in range(n) because Py_None is immortal on 3.12+ and skips the store-cycle refcount work that range's small-int yields incur), 5.2× display-on throughput vs tqdm, ~50× vs rich / alive, 600×+ less Python heap peak, 2× tighter tail latency, 3× faster first-frame paint than tqdm, and ~50× less CPU than rich / alive over 20 M iterations. The sub-1.0 CPU/wall ratio reflects the decoupled render thread: it wakes on a 50 ms timeout, formats into a preallocated buffer, and spends most of its life parked on a condition variable, so the producer loop never pays for rendering inline.

Import startup (median, baseline-subtracted, 11 runs)

Measured by timing python -c "from <lib> import ..." in a subprocess and subtracting a bare-interpreter baseline (python -c "pass"), so the number is just the work the library does at import time. BarFlow's module graph is deliberately lazy: themes, columns, style, spinners, hooks, and aio are all resolved on first attribute access via __getattr__, so the cold import only pays for the C extension load and an __init__.py that does nothing but expose Progress, Tracker, and track.

No-display hot path — pure per-tick overhead

Display is disabled (disable=True where the library supports it) so we measure the cost of advancing the counter, not rendering. ns/iter is over the bare for-loop baseline.

• barflow-iter is for _ in p: — BarFlow's Progress type implements the iteration protocol directly, so FOR_ITER dispatches tp_iternext without the CPython vectorcall trampoline. The iternext body is three x86 instructions (load, fetch_add, return Py_None), and Py_None's immortal refcount on 3.12+ means the loop's STORE_FAST _ is free. Net result: below the bare for-loop baseline, because a range-driven loop still does refcount work on its cached small-int yields.
• barflow-track is the for x in barflow.track(iterable): wrapper, used when you also need the yielded values.
• barflow-tick is the manual Progress.tick() call from Python, which pays the full CPython vectorcall dispatch overhead per call. Use the iteration protocol above when you don't have a source iterable.

Display on — throughput with a live renderer

Comparator libraries write into an io.StringIO sink with force_terminal=True so no real console I/O is measured. BarFlow writes to its native Windows console path (no sink parameter), which makes the comparison conservatively worse for BarFlow.

BarFlow's render loop emits delta frames: each column's previously-rendered bytes are cached, and on the next frame the render thread emits \x1b[<n>C (cursor-right) over unchanged spans instead of re-writing the bytes. On a real TTY this cuts bytes-written per frame by roughly 60% for the default layout; the sink-based benchmark above does not exercise the delta path, so the number you see is the lower bound — real terminals get more.

Memory footprint

tracemalloc peak is the high-water mark of the Python heap over a 1 M-iteration run (bench_memory.py). BarFlow's ~500 bytes is effectively one Progress object's shell — the counter, output buffer, render thread, and render scratch all live in C-owned storage that tracemalloc cannot see. Competitors allocate hundreds of KB to several MB of Python objects per run.

Tail latency (per-iter distribution, display on)

Per-iter timestamps recorded with perf_counter_ns() across 100 K iterations; bench_tail_latency.py. BarFlow is the only library whose p99.9 does not diverge from its p50 — the render thread never spills work onto the producer, so there is no jitter source to create tail spikes.

First-frame latency (__enter__ to first byte)

BarFlow paints a synchronous first frame on Progress.__enter__ before the render thread takes over, eliminating the 50 ms "blank bar" window that would otherwise be visible for short-lived jobs. Measured by bench_first_frame.py.

Multi-bar throughput (4 concurrent tasks)

4 tasks × 250 K ticks each, driven round-robin from one thread (bench_multibar.py). BarFlow stays lock-free — every task has its own cache-line-padded counter, and the render thread walks the task vector under a mutex that the single-task hot path never touches. The multi-task update(task_id, n) does take that mutex to resolve the task pointer, but holds the GIL across it — skipping the per-call thread-state save/restore — whenever no CallbackColumn is present, which is the only case where the render thread needs the GIL while holding the lock. (bench_multibar.py numbers above are a pinned Python 3.13 run; the GIL-held path's speedup is larger on 3.14, where GIL save/restore costs more.)

Metadata churn (description updated every 1 K iters)

1 M ticks, set_description called every 1000 ticks with a pre-generated 40-char string (bench_metadata_churn.py). BarFlow exposes set_description(str) and set_task_description(task_id, str) that briefly acquire the render mutex to swap the description; the lock-free tick hot path is unaffected.

CPU cost — render thread counted

time.process_time() sums user+system time across every thread of the process (Windows GetProcessTimes, Linux CLOCK_PROCESS_CPUTIME_ID, macOS task_info), so a background render thread cannot hide from this measurement.

Two things stand out:

1. BarFlow's CPU cost is identical whether the display is on or off. Turning the bar on adds no measurable per-iter CPU because the render thread wakes on a 50 ms condition-variable timeout and spends the rest of its life parked. The producer loop sees the same hot path in both modes.
2. tqdm's CPU grows 3.6× when the display turns on (266 → 953 ms), because rendering runs inline on the producer thread. Rich and alive-progress sit near ~50× BarFlow's CPU cost in both modes — they pay hundreds of nanoseconds of dict/lock work per advance() call before any rendering happens.

Caveats / reproducibility

• Numbers are from a single Windows 11 box; absolute values will differ on Linux / macOS but the ratios are stable in repeated runs. Re-run python benchmarks/bench.py --n 20000000 --runs 5 to reproduce the main table, and python benchmarks/bench_*.py for each extra axis (tail latency, memory, first-frame, multi-bar, metadata churn).
• tqdm is run with mininterval=0.05 (matching BarFlow's default) rather than its out-of-box 0.10, so the comparison isolates per-render work from render frequency instead of giving tqdm a free 2× render-skip advantage.
• time.process_time() resolution is ~15 ms on Windows, so the smallest CPU numbers (barflow: 187 ms) sit only ~12 ticks above noise floor. Differences against tqdm (5×) and rich/alive (~50×) are well outside that window.
• Display-on throughput is measured against an io.StringIO sink, which skips Windows console latency. On a real TTY, BarFlow's delta-render (cursor-advance over unchanged column spans) gives it additional headroom that the StringIO harness cannot see.

Install

pip install barflow

Wheels are published for Windows (AMD64), Linux (x86_64, aarch64), and macOS (x86_64, arm64) for CPython 3.10 through 3.15, including the free-threaded cp314t and cp315t builds.

Features

• Zero-overhead iteration. for _ in progress: runs at 160+ M it/s — below the bare for _ in range(n) baseline, because FOR_ITER dispatches directly to tp_iternext (no vectorcall trampoline) and Py_None is immortal on 3.12+ (no refcount work on STORE_FAST).
• C++ hot path. tick, advance, and Tracker's iter-next are single std::atomic::fetch_add calls with no locks and no Python-level bookkeeping. Task counters are cache-line padded so the render thread's reads never false-share with producer writes.
• Decoupled renderer. A background thread wakes on a 50 ms condition-variable timeout and formats into a preallocated buffer. The producer never blocks.
• Delta-render. The render loop caches each column's previous bytes and emits \x1b[<n>C cursor-advance over unchanged spans instead of rewriting the frame. Roughly 60% fewer bytes written per frame on the default layout.
• Synchronous first frame. Progress.__enter__ paints one frame inline before the render thread takes over, so short-lived jobs don't see the 50 ms blank-bar window.
• Native console I/O on every OS. Windows: unconditional ENABLE_VIRTUAL_TERMINAL_PROCESSING, UTF-16 transcoded WriteConsoleW chunked at 32 KB, legacy-console fallback, no colorama dependency, and a reusable wscratch transcoding buffer so steady-state frames are zero-alloc. POSIX (macOS/Linux): native ANSI write(2) to fd 2 with TIOCGWINSZ width detection. Same rendering core behind a thin platform shim.
• Multi-task + columns. 11 built-in column types (description/bar/percent/count/rate/elapsed/eta/spinner/text/postfix — all in C++ — plus a Python-rendered callback column), rich-style column API, themes, ANSI cursor stacking for nested bars. Progress.set_description(str) and set_task_description(task_id, str) expose metadata churn without touching the lock-free hot path.
• tqdm-shaped ergonomics. reset(task_id, total) restarts a bar for reuse across phases; set_postfix(loss=…, acc=…) adds a live trailing annotation (the default layout carries it invisibly until set); unit="B", unit_scale=True, unit_divisor=1024 humanizes counts/rate for byte transfers (1.50M/4.10M, … B/s); smoothing=0.3 swaps the whole-run average rate for an EMA that tracks current speed; leave=False clears the bar on completion. Progress.total / .elapsed read task 0, and list(track(range(n))) preallocates via __length_hint__.
• More tqdm/rich parity. barflow.wrap_file(fileobj, total=…) / wrapattr meter a stream's byte throughput (read/write) through a transparent proxy; initial= resumes a partially-done job (shown but excluded from the rate); set_visible(task_id, bool) hides/shows a task's row while it keeps counting; delay= suppresses the bar until it has run longer than N seconds; disable=None auto-disables when stderr is not a TTY (so piped/redirected runs stay clean).
• Spinner DSL. Compositional factories (frame / scrolling / bouncing / alongside / sequential) compile to precomputed frame tables at __enter__.
• print() interception. capture_output=True reroutes sys.stdout through write_above() so user prints appear above live bars without tearing.
• asyncio. barflow.aio.atrack(aiter) wraps async iterables.
• Tiny cold import. import barflow is ~1.2 ms (baseline-subtracted median) — 25–62× faster than the alternatives. All non-core submodules (themes, columns, spinners, style, hooks, aio) are lazy-loaded via PEP 562 __getattr__.
• Sub-kilobyte Python heap. Peak tracemalloc usage across a 1 M-iteration run is ~500 bytes, vs 300 KB (tqdm), 660 KB (rich), and 3.4 MB (alive-progress).

Usage

import barflow
from barflow.columns import (
    SpinnerColumn, DescriptionColumn, BarColumn, PercentColumn,
    CountColumn, RateColumn, EtaColumn,
)

# Simplest form — when you need the iterated values
for x in barflow.track(range(1000), desc="task"):
    ...

# Fastest form — when you just need a counter
with barflow.Progress(total=1000, desc="task") as p:
    for _ in p:
        do_work()

# Custom columns
with barflow.Progress(
    SpinnerColumn(name="dots"), " ",
    DescriptionColumn(), " ",
    BarColumn(width=40, color="magenta"), " ",
    PercentColumn(), "  ",
    CountColumn(), " | ", EtaColumn(),
    total=1000, desc="build",
) as p:
    for _ in range(1000):
        p.tick()

# Named theme
with barflow.Progress(theme="classic", total=1000) as p:
    ...

# Multi-task
with barflow.Progress(theme="classic") as p:
    dl = p.add_task(total=100, desc="download")
    ex = p.add_task(total=100, desc="extract")
    for i in range(100):
        p.update(dl, 1)
        p.update(ex, 1)

# Live prints during a bar
with barflow.Progress(total=100, capture_output=True) as p:
    for i in range(100):
        if i % 10 == 0:
            print(f"checkpoint {i}")   # appears above the bar
        p.tick()

# Byte transfer — humanized count/rate, EMA-smoothed speed
with barflow.Progress(total=4_100 * 1024, desc="download.iso",
                      unit="B", unit_scale=True, unit_divisor=1024,
                      smoothing=0.3) as p:
    while not done:
        chunk = recv()
        p.advance(len(chunk))       # renders 1.50M/4.10M … 3.2M B/s

# Training loop — reuse one bar across epochs, live metrics
with barflow.Progress(total=steps, smoothing=0.4) as p:
    for epoch in range(epochs):
        p.reset(total=steps)                       # restart counter + timers
        p.set_description(f"epoch {epoch}")
        for step in range(steps):
            p.advance(1)
            p.set_postfix(loss=loss, acc=acc)      # … loss=0.031, acc=0.98

# asyncio
import asyncio, barflow.aio as aio
async def main():
    async for x in aio.atrack(some_async_iter(), total=1000):
        ...
asyncio.run(main())

Design

See docs/DESIGN.md for the full architecture: atomic hot path, background render thread, column pipeline, Windows console handling, and the benchmarks methodology.

Build from source

Requires Visual Studio 2022+ (Windows) or GCC/Clang + Python headers (POSIX) and Python ≥ 3.10.

# Windows
build.bat

# POSIX
python -m pip install -e .

License

MIT. See LICENSE.