Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python Rich Progress Bars, Spinners, and Status

Learn how to add Rich progress bars, spinners, and status messages to Python CLI apps, with working examples and configuration details.

~6 min readPython
#Rich#progress bars#spinners#terminal UI
Illustration of a Python terminal with progress bars, spinners, and status indicators.

When a Python command-line tool runs a long operation, users need feedback. The Rich library provides three primary mechanisms for that feedback: progress bars, spinners, and status messages. This article shows how to use those mechanisms in real CLI applications, with working examples and configuration details.

What Rich Provides for Progress Indication

Rich offers three distinct components for displaying progress in a terminal:

  • Progress bars for tasks with known total work or a defined number of steps.
  • Spinners for indeterminate operations where the completion point is unknown.
  • Status messages for showing a short-lived message while a task runs.

Each component is rendered by Rich's live display engine, which redraws the terminal output in place. This keeps the interface clean and avoids flooding the console with repeated lines.

The core APIs are Progress, Spinner, and Status from Rich's rich.progress, rich.spinner, and rich.status modules. You can use them independently or combine them to match the nature of the operation you are reporting.

Building a Basic Progress Bar

The Progress class is the most common way to show a determinate task. You create an instance, add a task with a known total, and update the task's progress as work completes.

python
from rich.progress import Progress import time with Progress() as progress: task = progress.add_task("Processing files", total=100) for i in range(100): time.sleep(0.02) progress.update(task, advance=1)

The add_task method returns a task ID, which you use in update to advance the progress. The advance parameter increments the completed amount. When the task reaches the total, the bar fills completely and the task is marked as finished.

The with block ensures the live display starts and stops correctly. Without it, you would need to call start() and stop() manually.

If you have a simple loop over a known iterable, Rich provides the track convenience function that wraps an iterable and displays a progress bar automatically.

python
from rich.progress import track import time for item in track(range(100), description="Processing"): time.sleep(0.02)

track is ideal for quick scripts where you do not need fine-grained control over the task ID.

Customizing Progress Bar Columns

By default, a progress bar shows a description, a bar, a percentage, and a time estimate. You can change the columns to show different information, such as transfer speed, file count, or a custom field.

Rich uses the Progress constructor's columns parameter to accept a list of column objects. For example, to show the task description and a transfer speed:

python
from rich.progress import Progress, BarColumn, TextColumn, TransferSpeedColumn progress = Progress( TextColumn("[progress.description]{task.description}"), BarColumn(), TextColumn("[progress.percentage]{task.percentage:>3.0f}%"), TransferSpeedColumn(), )

Each column can be configured with format strings and styles. The task object inside the format string exposes fields like description, percentage, completed, total, and elapsed.

You can also set the bar width, change the bar character, or add a spinner column to the progress display. The following table lists common column classes and their purpose:

Column classPurpose
TextColumnDisplay a formatted text field
BarColumnRender the visual progress bar
SpinnerColumnDisplay an animated spinner in the progress display
TimeElapsedColumnShow time elapsed since the task started
TimeRemainingColumnShow estimated time remaining
TransferSpeedColumnShow bytes per second (for file transfers)

To display a percentage, use a TextColumn with the {task.percentage} field. These columns can be mixed and matched to fit the information your users need.

Using Spinners for Indeterminate Work

When you cannot know how long an operation will take, a spinner provides visual feedback without implying a completion percentage. Rich's Spinner class renders an animated character that cycles through a set of frames.

python
from rich.console import Console import time console = Console() with console.status("Working..."): time.sleep(3)

The console.status context manager is a convenient wrapper that shows a spinner with a message. It is perfect for operations that do not need a progress bar, such as connecting to a remote service or parsing a large file.

If you need more control, you can create a Spinner instance directly and render it in a loop:

python
from rich.spinner import Spinner from rich.console import Console import time console = Console() spinner = Spinner("dots", text="Loading") with console.live(spinner): for _ in range(10): time.sleep(0.1)

Rich includes many spinner styles, such as dots, line, arrow, and aesthetic. You can list them with rich.spinner.SPINNERS or by running python -m rich.spinner in the terminal.

Showing Status Messages

The Status class is similar to a spinner but is designed for short-lived messages that disappear when the operation completes. It is often used to indicate that a step is in progress without permanently occupying the terminal.

python
from rich.console import Console import time console = Console() with console.status("Uploading...") as status: time.sleep(2) status.update("Uploaded, now verifying...") time.sleep(2)

The status.update method lets you change the message while the operation runs. This is useful for multi-stage processes where you want to inform the user of the current step.

Unlike a progress bar, a status message does not show a percentage or a bar. It is best used for operations that are too short or too unpredictable to warrant a progress bar.

Handling Concurrent Tasks

The Progress class supports multiple tasks running concurrently. You can add several tasks and update them independently, which is useful for parallel downloads or processing multiple files.

python
from rich.progress import Progress import time with Progress() as progress: task1 = progress.add_task("Task A", total=100) task2 = progress.add_task("Task B", total=100) for i in range(100): time.sleep(0.01) progress.update(task1, advance=1) progress.update(task2, advance=1)

Rich displays each added task as a separate row in the same live display, so you can track several operations without creating a separate progress bar for each one.

If you update a Progress instance from multiple threads, coordinate updates with a lock or route them through a single owner thread. For asyncio code, avoid blocking the event loop while a Progress display is active and serialize updates from concurrent tasks with a lock or queue.

Performance and Refresh Overhead

Each progress.update may trigger a refresh, but Rich batches rapid updates to avoid redrawing too often. The default refresh_per_second is 10, so the refresh interval defaults to 0.1 seconds. Updates that happen faster than that are rendered on the next refresh tick.

You can adjust the refresh rate with the refresh_per_second parameter in the Progress constructor. For very fast operations, you might want to lower the refresh rate to reduce CPU usage. For animations that need to be smooth, you can increase it, but be mindful of the overhead.

python
progress = Progress(refresh_per_second=30)

In practice, the overhead of a progress bar is negligible compared to the actual work in most CLI tools. The main concern is avoiding excessive updates in tight loops that do not do significant work.

Terminal Compatibility and Non-Interactive Output

Rich detects whether the output is a terminal. When the output is redirected to a file or piped to another program, Rich disables the live display and falls back to printing the final state. This is important for scripts that are run in CI pipelines or with cron.

For progress bars, this means that in non-interactive mode, you might see the final line printed once instead of an animated bar. You can control this behavior by creating a Console(force_terminal=True) and passing it to Progress (or using it for console.status), but it is usually best to let Rich decide automatically.

Spinners and status messages also degrade gracefully. In a non-terminal context, they simply print the message once without animation. This ensures that your logs remain readable and do not contain escape sequences.

If you are integrating Rich with a logging framework, be aware that the live display can interfere with log output. A common pattern is to use rich.logging.RichHandler with the same Console; test your setup to make sure log messages do not disrupt the live region.

When building a CLI that must work in both interactive and non-interactive environments, test both modes. You can simulate a non-terminal by piping the output to cat or redirecting to a file.

Rich's progress, spinner, and status components are powerful tools for improving the user experience of Python command-line applications. By understanding their configuration options and runtime behavior, you can add clear, responsive feedback to any long-running task.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.