alive-progress

3.3.0 · active · verified Fri Apr 10

alive-progress is a versatile and highly customizable Python library for creating animated progress bars in the terminal. It provides visual feedback for long-running tasks with real-time throughput, Estimated Time of Arrival (ETA), and a variety of cool animations. Currently at version 3.3.0, the library maintains an active development and release cadence, offering robust features for CLI applications.

Warnings

gotcha When running in non-interactive environments like PyCharm consoles, Jupyter notebooks, or shell pipelines, alive-progress might automatically detect a non-TTY environment and only print the final receipt. To force the progress bar display, use the `force_tty=True` argument.
Fix: Use `with alive_bar(total, force_tty=True) as bar:` to explicitly enable the display in such environments.
breaking The method for setting inline messages within the progress bar changed in earlier major versions. Older versions used `bar('message')` to set text while incrementing. Current versions (3.x) use `bar(text='message')` for this purpose. Calling `bar('message')` without the `text=` keyword in 3.x will likely result in an error or unexpected behavior as it would try to interpret 'message' as an increment count.
Fix: Always use the `text='your message'` keyword argument when setting an inline message: `bar(text='current status')`. The `bar()` call without arguments increments the bar.
gotcha When `alive_bar` is initialized with a `total`, calling `bar()` without arguments increments an internal counter. To manually set the progress by a percentage (e.g., 15%), you must pass the fractional value to `bar()`: `bar(0.15)`. Mixing these approaches or passing a raw count when percentage is expected (or vice-versa) without understanding the mode can lead to incorrect progress display.
Fix: If `total` is provided, `bar()` increments. To set a specific percentage, call `bar(fractional_value)` (e.g., `bar(i / total)`). If no `total` is given, it operates in 'unknown' mode with no ETA, and `bar()` simply updates the spinner.
deprecated Support for older Python versions has been dropped. The library officially supports Python >=3.9.
Fix: Ensure your project uses Python 3.9 or newer.

Install

pip install alive-progress Install latest version

Imports

alive_bar
```
from alive_progress import alive_bar
```
alive_it
```
from alive_progress import alive_it
```
A convenient wrapper for iterables, automatically handling bar updates.

Quickstart

This quickstart demonstrates the most common usage pattern for `alive-progress` using the `alive_bar` context manager. It initializes a progress bar with a total count and updates it in each iteration of a loop.

import time
from alive_progress import alive_bar

TOTAL_ITEMS = 100

with alive_bar(TOTAL_ITEMS, title='Processing items') as bar:
    for i in range(TOTAL_ITEMS):
        # Simulate a task
        time.sleep(0.05)
        bar() # Update the progress bar

print("Task completed!")

view raw JSON →