This page is the API reference for rich.progress — covering the Progress class, Task dataclass, all ProgressColumn subclasses, and the module-level convenience functions track(), wrap_file(), and open(). It also documents ProgressBar from rich.progress_bar, which is the low-level rendering primitive used by BarColumn.
For conceptual usage and examples, see Progress Bars. For the Live display system that Progress builds on, see Live Display.
| Symbol | Definition | Description |
|---|---|---|
TaskID | NewType("TaskID", int) | Opaque integer identifier for a task |
ProgressType | TypeVar("ProgressType") | Generic type variable for sequence elements |
GetTimeCallable | Callable[[], float] | A zero-arg callable returning the current time as a float |
Class hierarchy of Progress API types:
Sources: rich/progress.py507-924 rich/progress.py935-1061 rich/progress_bar.py18-207
Progress ClassProgress is the main class. It wraps a Live display and manages a collection of Task objects, rendering them as a table of progress bars and columns.
Progress(
*columns,
console=None,
auto_refresh=True,
refresh_per_second=10,
speed_estimate_period=30.0,
transient=False,
redirect_stdout=True,
redirect_stderr=True,
get_time=None,
disable=False,
expand=False,
)
| Parameter | Type | Default | Description |
|---|---|---|---|
*columns | ProgressColumn | str | (default set) | Column objects or literal strings to display. If none provided, uses get_default_columns() |
console | Optional[Console] | None | Console to render to. Creates an internal one if None |
auto_refresh | bool | True | If True, a background thread refreshes the display at refresh_per_second |
refresh_per_second | float | 10 | Number of refreshes per second when auto_refresh=True |
speed_estimate_period | float | 30.0 | Duration in seconds used for the rolling speed estimate window |
transient | bool | False | If True, clears the progress display when stopped |
redirect_stdout | bool | True | Redirect sys.stdout through the Live display while active |
redirect_stderr | bool | True | Redirect sys.stderr through the Live display while active |
get_time | Optional[GetTimeCallable] | None | Callable returning current time. Defaults to monotonic |
disable | bool | False | If True, suppresses all display and does not start Live |
expand | bool | False | Expand the progress table to fill terminal width |
Progress implements __enter__ / __exit__. Entering calls start(), exiting calls stop(). Both start() and stop() are safe to call multiple times.
Progress.get_default_columns() → Tuple[ProgressColumn, ...]
Returns the default column set: TextColumn, BarColumn, TaskProgressColumn, TimeRemainingColumn.
| Method | Signature | Returns | Description |
|---|---|---|---|
add_task | (description, start=True, total=100.0, completed=0, visible=True, **fields) | TaskID | Creates and registers a new task |
remove_task | (task_id) | None | Removes a task from the display |
update | (task_id, *, total=..., completed=..., advance=..., description=..., visible=..., refresh=False, **fields) | None | Updates one or more fields of a task |
advance | (task_id, advance=1) | None | Increments completed by advance |
reset | (task_id, *, start=True, total=..., completed=0, visible=True, description=..., **fields) | None | Resets a task's progress and clears speed samples |
start_task | (task_id) | None | Marks a task as started (sets start_time) |
stop_task | (task_id) | None | Marks a task as stopped (sets stop_time) |
add_task Parameters| Parameter | Type | Default | Description |
|---|---|---|---|
description | str | — | Text label shown next to the bar |
start | bool | True | Whether to start timing immediately |
total | Optional[float] | 100.0 | Total steps. Set to None for an indeterminate (pulsing) bar |
completed | int | 0 | Initial completed count |
visible | bool | True | Whether to show in the display |
**fields | Any | — | Arbitrary extra fields stored in task.fields, accessible in TextColumn format strings |
update ParametersAny combination of the following keyword arguments may be passed:
| Keyword | Description |
|---|---|
total | New total value |
completed | Set completed to an absolute value |
advance | Add to the current completed value |
description | Change the description text |
visible | Show or hide the task |
refresh | Force an immediate display refresh if True |
**fields | Update arbitrary fields in task.fields |
| Method | Description |
|---|---|
refresh() | Force an immediate re-render |
start() | Start the Live display and background refresh thread |
stop() | Stop the Live display; finalizes the output |
Progress.track(sequence, total=None, completed=0, description="Working...", update_period=0.1) → Iterable
Wraps an iterable, advancing the task for each item yielded. Uses _TrackThread internally to throttle updates. Progress must already be started (used inside a with Progress() block).
Progress.wrap_file(file, total, *, task_id=None, description="Reading...") → _Reader
Returns a _Reader wrapping a BinaryIO object that advances a task by the number of bytes read. If task_id is not provided, a new task is created.
Progress.open(file, mode="r", *, total=None, description="Reading...", ...)
Opens a file path and wraps it in a _Reader. Automatically uses os.stat to determine total for paths if not specified. Supports modes "r", "rt", and "rb".
| Property | Type | Description |
|---|---|---|
task_ids | List[TaskID] | IDs of all non-removed tasks |
tasks | List[Task] | All task objects (including hidden ones) |
finished | bool | True when all tasks are complete |
live | Live | The underlying Live instance |
Sources: rich/progress.py1061-1400 tests/test_progress.py168-210
Task DataclassTask stores all state for a single progress item. Instances are created by Progress.add_task() and should be treated as read-only outside of Progress.
| Field | Type | Description |
|---|---|---|
id | TaskID | Unique identifier |
description | str | Label string |
total | Optional[float] | Total steps; None means indeterminate |
completed | float | Steps completed so far |
visible | bool | Display visibility flag |
fields | Dict[str, Any] | Custom fields from update(**fields) |
start_time | Optional[float] | Monotonic time when task was started |
stop_time | Optional[float] | Monotonic time when task was stopped |
finished_time | Optional[float] | Time the task was marked finished |
finished_speed | Optional[float] | Captured speed at finish time |
| Property | Type | Description |
|---|---|---|
started | bool | True if start_time is set |
finished | bool | True if finished_time is set |
elapsed | Optional[float] | Seconds since start; stops updating after stop_time |
remaining | Optional[float] | total - completed, or None if total is None |
percentage | float | 0–100 percentage; returns 0.0 if total is None or zero |
speed | Optional[float] | Rolling average steps/sec computed from _progress samples |
time_remaining | Optional[float] | Estimated seconds to completion, or None if unknown |
The _progress deque stores up to 1000 ProgressSample entries for the speed estimate.
ProgressSample NamedTupleProgressSample(timestamp: float, completed: float)
Captures a timestamped snapshot of completed for the rolling speed calculation.
Sources: rich/progress.py926-1058 tests/test_progress.py411-486
ProgressColumn — Base Class and SubclassesProgressColumn is an abstract base class. Each column is called with a Task and returns a renderable. Columns are assembled into a Table row by Progress.
ProgressColumn base class:
| Attribute / Method | Description |
|---|---|
max_refresh | Optional[float] — If set, limits re-rendering to at most once per this many seconds. None means always re-render |
get_table_column() | Returns the Column config used to build the internal table |
render(task) | Abstract. Must return a RenderableType |
__call__(task) | Handles the cache check against max_refresh, then delegates to render() |
Data flow through a column:
Sources: rich/progress.py507-543
Column rendering and data access map:
Sources: rich/progress.py549-924
TextColumnRenders a formatted string using Python's str.format() with task as the variable. Optionally parses markup.
| Parameter | Type | Default | Description |
|---|---|---|---|
text_format | str | — | Format string, e.g. "{task.description}" |
style | StyleType | "none" | Text style |
justify | JustifyMethod | "left" | Text alignment |
markup | bool | True | Parse Rich markup in the result |
highlighter | Optional[Highlighter] | None | Highlighter applied after formatting |
table_column | Optional[Column] | Column(no_wrap=True) | Column configuration |
BarColumnRenders the visual progress bar by producing a ProgressBar renderable.
| Parameter | Type | Default | Description |
|---|---|---|---|
bar_width | Optional[int] | 40 | Fixed width in chars; None for full terminal width |
style | StyleType | "bar.back" | Background (unfilled) style |
complete_style | StyleType | "bar.complete" | Filled portion style |
finished_style | StyleType | "bar.finished" | Style when task is at 100% |
pulse_style | StyleType | "bar.pulse" | Pulsing animation style (indeterminate tasks) |
table_column | Optional[Column] | None | Column configuration |
When task.started is False, the bar pulses regardless of completed.
SpinnerColumnShows a spinner animation while the task is running; shows finished_text when done.
| Parameter | Type | Default | Description |
|---|---|---|---|
spinner_name | str | "dots" | Name of the spinner (see python -m rich.spinner) |
style | Optional[StyleType] | "progress.spinner" | Spinner style |
speed | float | 1.0 | Speed multiplier |
finished_text | TextType | " " | Text displayed when task is finished |
set_spinner(spinner_name, spinner_style, speed) — Replaces the spinner at runtime.
TaskProgressColumnSubclass of TextColumn. Shows percentage by default; shows speed instead when total is None and show_speed=True.
| Parameter | Type | Default | Description |
|---|---|---|---|
text_format | str | "[progress.percentage]{task.percentage:>3.0f}%" | Format when total is known |
text_format_no_percentage | str | "" | Format when total is None |
show_speed | bool | False | Show iterations/sec when total is unknown |
TaskProgressColumn.render_speed(speed) (classmethod) — Formats speed as "N.N it/s" with SI suffixes (×10³, ×10⁶, etc.).
TimeElapsedColumnRenders elapsed time as H:MM:SS. Shows "-:--:--" before the task starts. Uses task.finished_time when finished.
Style: "progress.elapsed"
TimeRemainingColumnRenders estimated time remaining. Updates at most twice per second (max_refresh = 0.5) to prevent jitter.
| Parameter | Type | Default | Description |
|---|---|---|---|
compact | bool | False | Show MM:SS instead of H:MM:SS when under 1 hour |
elapsed_when_finished | bool | False | Show elapsed time (not 0) once the task finishes |
Shows "-:--:--" (or "--:--" in compact mode) when estimate is unavailable. Returns empty string if total is None.
FileSizeColumnRenders task.completed as a human-readable byte size using decimal units (e.g., "1.5 MB").
Style: "progress.filesize"
TotalFileSizeColumnRenders task.total as a human-readable byte size.
Style: "progress.filesize.total"
DownloadColumnRenders completed/total in the same unit, e.g. "0.5/2.3 GB". Chooses the unit based on total (or completed if total is None).
| Parameter | Type | Default | Description |
|---|---|---|---|
binary_units | bool | False | Use KiB/MiB/GiB (1024-based) instead of kB/MB/GB (1000-based) |
TransferSpeedColumnRenders download speed as "N.N MB/s" using decimal units. Uses task.finished_speed if task is done, otherwise task.speed. Shows "?" if speed is unavailable.
Style: "progress.data.speed"
MofNCompleteColumnRenders completed/total as integers, e.g. " 10/1000". Space-pads the completed count to keep stable width as numbers grow.
| Parameter | Type | Default | Description |
|---|---|---|---|
separator | str | "/" | String between completed and total values |
RenderableColumnInserts a fixed arbitrary renderable into the column, independent of task state.
| Parameter | Type | Default | Description |
|---|---|---|---|
renderable | RenderableType | "" | Any renderable to display |
track()track(
sequence,
description="Working...",
total=None,
completed=0,
auto_refresh=True,
console=None,
transient=False,
get_time=None,
refresh_per_second=10,
style="bar.back",
complete_style="bar.complete",
finished_style="bar.finished",
pulse_style="bar.pulse",
update_period=0.1,
disable=False,
show_speed=True,
) -> Iterable[ProgressType]
Convenience wrapper that creates a Progress with TextColumn, BarColumn, TaskProgressColumn, and TimeRemainingColumn, then yields from Progress.track(). The with block is managed internally.
total defaults to len(sequence) via operator.length_hint. Pass an explicit total for generators with known length.
wrap_file()wrap_file(
file: BinaryIO,
total: int,
*,
description="Reading...",
...style args...,
disable=False,
) -> ContextManager[BinaryIO]
Returns a context manager that wraps an already-open binary file handle in a _Reader. The Progress display starts on context entry and stops on exit. Uses TextColumn, BarColumn, DownloadColumn, and TimeRemainingColumn.
open()open(
file: Union[str, PathLike, bytes],
mode: Literal["r", "rt", "rb"] = "r",
buffering=-1,
encoding=None,
errors=None,
newline=None,
*,
total=None,
description="Reading...",
...style args...,
disable=False,
) -> ContextManager[BinaryIO | TextIO]
Opens a file by path (or bytes path), wraps it in a _Reader, and returns a context manager. When mode="rb", returns ContextManager[BinaryIO]. When mode="r" or mode="rt", returns ContextManager[TextIO]. If total is None, uses os.stat(file).st_size.
ProgressBar WidgetProgressBar is the low-level renderable used by BarColumn. It implements __rich_console__ directly. It is a JupyterMixin.
| Parameter | Type | Default | Description |
|---|---|---|---|
total | Optional[float] | 100.0 | Total steps; None triggers pulse mode |
completed | float | 0 | Steps completed |
width | Optional[int] | None | Fixed width; None for full available width |
pulse | bool | False | Force pulse animation regardless of completion |
style | StyleType | "bar.back" | Background style |
complete_style | StyleType | "bar.complete" | Fill style |
finished_style | StyleType | "bar.finished" | Style at 100% |
pulse_style | StyleType | "bar.pulse" | Pulse animation style |
animation_time | Optional[float] | None | Explicit animation timestamp; uses monotonic() if None |
update(completed, total=None) — Updates internal completed and optionally total.
percentage_completed (property) — Returns the percentage as a float (0–100), or None if total is None.
pulse=True or total is None: renders an animated wave using _render_pulse(), cycling through 20 color-blended segments (PULSE_SIZE).━ characters (or - on ASCII/legacy Windows), with half-block precision characters ╸/╺ for sub-character positioning.completed >= total: uses finished_style for the entire bar.Sources: rich/progress_bar.py18-207 tests/test_bar.py1-98
_TrackThread rich/progress.py64-101 — A daemon thread used by Progress.track(). It periodically calls progress.advance() based on bytes/items read from an external counter (self.completed). Stops via an Event and is used as a context manager.
_Reader rich/progress.py182-282 — A RawIOBase / BinaryIO proxy that calls progress.advance() on every read(), readline(), readlines(), readinto(), and __next__(). Calls progress.update(completed=pos) on seek(). Used by wrap_file() and open().
_ReadContext rich/progress.py285-303 — A ContextManager that calls progress.start() on enter and progress.stop() on exit, coordinated with a _Reader.
Sources: rich/progress.py64-368
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.