ProgressBar API#

Run this demo live in your browser ▶

ProgressBar draws a bar that fills as value climbs towards max_value, with a color, width, height and an optional value / max readout underneath. The reason it exists is that it does not depend on ipywidgets, so a loop that assigns bar.value reports progress the same way in whatever notebook you happen to be running, and it follows the surrounding light or dark theme.

See also: HTMLRefreshWidget for status text updated in place next to it, AnnotationWidget for the labeling queue that bar is often counting, and PlaySlider when the value should be driven by the reader instead.

Script mode: a rich terminal bar#

The same ProgressBar works outside a notebook too. When the code runs as a script — either a plain Python file or a marimo notebook run with uv run notebook.py — and the optional rich library is installed, each bar.value assignment is mirrored into a fancy animated bar in the terminal: a spinner, a bar colored from color, a percentage, an M/N count (shown when show_text is True) and a time-remaining estimate. Because the value is applied as an absolute position, the terminal bar moves backward too if value decreases.

marimo distinguishes these modes with mo.app_meta().mode ("edit"/"run" in the browser, "script" on the command line), and ProgressBar keys off the same signal — so one notebook shows the browser widget when edited and the rich bar when executed. No changes to your loop are needed either way:

import time
from wigglystuff import ProgressBar

bar = ProgressBar(max_value=50)
for i in range(51):
    bar.value = i
    time.sleep(0.05)

Install rich with pip install rich. If rich is not installed, or the code runs inside a notebook editor, this behaves exactly as before — nothing extra is rendered.

import time
import marimo as mo
from wigglystuff import ProgressBar

progress = mo.ui.anywidget(ProgressBar(value=0, max_value=100))

for i in range(101):
    progress.value = i
    time.sleep(0.1)

240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261

def __init__(self, value: int = 0, max_value: int = 100, color: str = '#22c55e', show_text: bool = True, width: str = '100%', height: int = 24):
    super().__init__()
    self.value = value
    self.max_value = max_value
    self.color = color
    self.show_text = show_text
    self.width = width
    self.height = height

    # In script mode, mirror progress into a rich terminal bar (if rich is
    # installed). The display is created lazily on the first value change.
    self._rich_progress = None
    self._rich_task = None
    self._rich_enabled = False
    if not _in_notebook():
        try:
            import rich  # noqa: F401 -- availability probe only

            self._rich_enabled = True
            self.observe(self._on_value_change, names=["value", "max_value"])
        except Exception:
            self._rich_enabled = False

Synced traitlets#