progressbar2 Documentation

The MultiBar class (found in progressbar/multi.py) currently subclasses Python's dict. This means it behaves like a dictionary of ProgressBar objects, but users should be aware of several side effects caused by this inheritance:

• Auto-vivification: Accessing a missing key via __getitem__ (e.g., multi_bar['missing_key']) will automatically create and return a new bar for that key.
• Dual-key state: The state is managed by both the label (key) and the bar object itself.
• Print redirection: It uses monkeypatching to install print redirection (bar.print or self.print).

Because it is a dict subclass, standard mapping methods are available, but the API is expected to move toward a composition-based model in a future major version to remove the auto-vivification behavior.

class MultiBar(dict[str, bar.ProgressBar])

For simple tasks, use progressbar.progressbar() as an iterable wrapper. It will automatically manage the progress bar based on the length of the provided iterable.

import time
import progressbar

for item in progressbar.progressbar(range(100), desc='Loading'):
    time.sleep(0.02)

The generate_colors.py script is a maintenance tool used to regenerate the 256-colour table located in progressbar/terminal/colors.py. It derives every HSL value from its corresponding RGB value using HSL.from_rgb.

Note that the RGB values, xterm indices, colour names, and Python binding names are considered authoritative and are not modified by this script.

To run the script in place, provide the path to the target colors file as an argument. The script is idempotent. You can use the --check flag to verify if the currently committed file is up to date without making any changes.

# Regenerate the colors file in place
python tools/generate_colors.py progressbar/terminal/colors.py

# Verify if the file is up to date without writing changes
python tools/generate_colors.py progressbar/terminal/colors.py --check

If you use virtualenvwrapper, you can create a dedicated environment for progressbar2 and then install it using pip.

$ mkvirtualenv progressbar2
$ pip install progressbar2

To prevent standard print() statements from breaking the progress bar's visual layout in the terminal, initialize the ProgressBar with redirect_stdout=True. This ensures that printed text appears above the bar rather than overwriting it.

import time
import progressbar

bar = progressbar.ProgressBar(redirect_stdout=True)
for i in range(100):
    print('Some text', i)
    time.sleep(0.1)
    bar.update(i)

To reproduce the benchmark results and generate the report, run the following commands in your terminal:

python benchmarks/bench.py && python benchmarks/report.py

The full collection of runnable code examples for progressbar2 is maintained in the examples.py file within the repository. This file serves as the source of truth for the demonstrations shown in the usage guides and README.

python
# Refer to examples.py in the repository root for full runnable code

To prevent log messages from corrupting the progress bar display, you must wrap the standard streams. Use progressbar.streams.wrap_stderr() and progressbar.streams.wrap_logging() to ensure logs are printed cleanly above the bar. Additionally, set redirect_stderr=True in the ProgressBar constructor.

import logging
import progressbar

progressbar.streams.wrap_stderr()
progressbar.streams.wrap_logging()
logging.basicConfig()

with progressbar.ProgressBar(total=10, redirect_stderr=True) as bar:
    logging.warning('message above the bar')
    bar.update(1)

The simplest way to use progressbar is to instantiate a ProgressBar object and wrap an iterable. This allows you to iterate through your loop while the bar automatically updates based on the progress of the iterable.

import time
import progressbar

bar = progressbar.ProgressBar()
for i in bar(range(100)):
    time.sleep(0.02)

If you do not have pip installed, you can use easy_install to install progressbar2.

$ easy_install progressbar2

Install the library using pip to add progress bar functionality to your Python scripts.

pip install progressbar2