alive-progress

alive-progress is a Python library that replaces the static progress bar with a live-updating one: a spinner that speeds up or slows down to reflect actual processing throughput, an ETA computed with an exponential-smoothing algorithm, and a final receipt summarizing elapsed time, item count, and observed rate once the operation completes. It renders in a background thread at a fraction of the real iteration rate (roughly 60 updates per second regardless of how many million iterations you run), keeping CPU overhead low and the terminal free of spam.

Beyond the visual bar, it hooks into print() and the standard logging module so output emitted mid-run is cleanly interleaved with the bar instead of corrupting it, works safely across threads, and supports Jupyter notebooks and headless/CI environments by degrading gracefully. Its most distinctive feature is the ability to suspend an active bar, drop back into the Python REPL to inspect or fix in-flight state, and then resume exactly where it left off. A companion spinner/bar compiler and showtime()/demo tools let you preview and design custom animations before wiring them into your own code.

What You Get

• A live spinner and bar that visibly react to actual processing speed rather than ticking at a fixed rate
• An ETA computed with an exponential-smoothing algorithm, plus automatic unit scaling (SI, IEC) for throughput display
• Automatic hooks for print() and logging so any output during the run is cleanly enriched and interleaved with the bar
• A final receipt showing total items, elapsed time, and observed throughput, still accessible from the bar handle after completion
• Underflow/overflow detection that visually flags when you call bar() more or fewer times than the declared total
• A pause mechanism (ctrl_c-safe suspend) to drop back to the REPL mid-run and resume the same bar afterward
• A large library of built-in spinner and bar styles plus factories for building custom ones, previewable via showtime()
• Dual-line mode for showing a situational status message beneath the running bar

Common Use Cases

• Wrapping ETL or batch-processing loops that iterate over large datasets, queryset counts, or file lists
• Long-running downloads or uploads where users need live throughput and an accurate time-to-completion estimate
• Scripts run over SSH where a static or silent process risks looking hung or triggering a connection timeout
• Interactive data-processing sessions in IPython/Jupyter where you want to pause, patch a few records, and resume
• CLI tools that need to report progress without polluting output that also prints or logs during the run
• Simulating or resuming batch jobs where some items were already processed (skipped=True) so ETA stays accurate

Under The Hood

Architecture The package separates concerns cleanly across four subpackages: core (progress.py implements the alive_bar/alive_it context managers and orchestrates a background render thread; configuration.py validates and merges user options; calibration.py computes FPS calibration from throughput; hook_manager.py intercepts stdout and logging so output doesn’t corrupt the bar), animations (bars.py/spinners.py define animation primitives, and spinner_compiler.py precompiles full animation cycles ahead of time rather than computing frames on the fly), styles (built-in presets and the showtime()/exhibit browser), and utils (cells.py implements grapheme-cluster-aware terminal rendering so wide Unicode and emoji render correctly, timing.py holds the exponential-smoothing ETA/rate math, and terminal/ isolates platform-specific size/capability detection). alive_bar() validates config, spins up the render thread to decouple refresh rate from iteration rate, and installs the print/logging hooks for the duration of the with block.

Tech Stack Pure Python (99.5% of the codebase) with exactly two runtime dependencies: about_time==4.2.1 for elapsed-time/duration formatting and graphemeu==0.7.2, a maintained fork of the abandoned grapheme package, for correct wide-character segmentation. Packaging uses classic setup.py/setuptools and ships a py.typed marker for downstream type checkers. Officially supports Python 3.9 through 3.14. Development tooling includes ruff for linting, pytest/pytest-cov/pytest-sugar for testing, and nox for running the suite across environments, with coverage reported to Codecov/Coveralls.

Code Quality Fifteen test files under tests/, mirroring the animations, core, and utils subpackages, share fixtures via a top-level conftest.py. GitHub Actions runs the full pytest suite on every push and PR across a six-version Python matrix (3.9-3.14), and the package is typed (using typing/collections.abc generics) with a py.typed marker rather than relying on stub-only typing. Error handling for edge cases like Ctrl-C interruption and over/underflow counts is explicit and treated as first-class documented behavior rather than an afterthought.

What Makes It Unique The spinner compiler is genuinely uncommon for this category: instead of computing animation frames at render time, it precompiles entire animation cycles ahead of time so playback has no runtime overhead, and it supports advanced transforms (reshape, replace, transpose, randomize) on those precompiled cycles. Its grapheme-cluster-aware “Cell Architecture” correctly renders multi-codepoint emoji and wide Unicode across bars, spinners, and borders — most terminal progress libraries assume one character equals one cell and break on this input. The pause-and-resume mechanic, which lets you suspend a running bar, return to an interactive Python prompt to inspect or patch state, and then continue the exact same bar, has no direct equivalent in comparable libraries like tqdm.