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.

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.
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.
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:
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 class | Purpose |
|---|---|
TextColumn | Display a formatted text field |
BarColumn | Render the visual progress bar |
SpinnerColumn | Display an animated spinner in the progress display |
TimeElapsedColumn | Show time elapsed since the task started |
TimeRemainingColumn | Show estimated time remaining |
TransferSpeedColumn | Show 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.
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:
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.
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.
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.
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 toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.