Python Progressbar2 Library

4.5.0 verified Tue May 12 auth: no python install: verified

progressbar2 is an actively maintained Python library designed to provide visual, text-based progress bars for long-running operations in CLI applications. It is a fork of the original `progressbar` package, aiming for backwards compatibility while offering enhanced features and ongoing development. The current stable version is 4.5.0.

pip install progressbar2

Common errors

error ModuleNotFoundError: No module named 'progressbar' ↓

cause This error occurs when the `progressbar2` library is installed, but the user attempts to import the original, unmaintained `progressbar` package, or when neither `progressbar` nor `progressbar2` is installed but the code tries to import `progressbar`.

fix

Ensure progressbar2 is installed (pip install progressbar2) and import the ProgressBar class correctly using from progressbar import ProgressBar or import progressbar (then use progressbar.ProgressBar). The progressbar package on PyPI is different from progressbar2.

error TypeError: __init__() got an unexpected keyword argument 'max_value' ↓

cause This error typically arises when using an older version of the `progressbar` library or when `progressbar2` is installed but the code expects the `maxval` parameter (from the older API) instead of `max_value`. It can also happen if the old `progressbar` package is installed instead of `progressbar2`.

fix

Ensure progressbar2 is installed and updated (pip install --upgrade progressbar2). Use max_value instead of maxval when initializing the ProgressBar. Example: progressbar.ProgressBar(max_value=100).

error TypeError: 'module' object is not callable ↓

cause This error occurs when the user tries to call the `progressbar` module directly as a function (e.g., `progressbar()`) instead of instantiating the `ProgressBar` class within the module (e.g., `progressbar.ProgressBar()`). This often happens if both `progressbar` and `progressbar2` are confusingly present, or if the import statement is `import progressbar` and then the user mistakenly tries to call `progressbar()` instead of `progressbar.ProgressBar()`.

fix

Always instantiate the ProgressBar class from the progressbar module. If you imported with import progressbar, use bar = progressbar.ProgressBar(...). If you used from progressbar import ProgressBar, then use bar = ProgressBar(...).

error AttributeError: module 'progressbar' has no attribute 'streams' ↓

cause This error indicates that the installed `progressbar` package is the original, unmaintained version (or an incompatible version), which lacks the `streams` attribute present in `progressbar2`.

fix

Uninstall any older progressbar package (pip uninstall progressbar) and then install progressbar2 (pip install progressbar2) to ensure you are using the actively maintained version that includes the streams functionality.

error ValueError: Value X is out of range, should be between 0 and Y ↓

cause This error occurs when the `update()` method of the progress bar is called with a value that is outside the defined `max_value` (or `maxval` in older versions) range.

fix

Ensure that the value passed to progress.update() is always within the valid range of 0 to max_value (inclusive). Double-check the loop or calculation that determines the update value to prevent it from exceeding max_value.

Warnings

gotcha The installed package is named `progressbar2`, but you must import `progressbar` in your Python code. Attempting to `import progressbar2` will result in an `ImportError`. ↓

fix Always use `import progressbar` or `from progressbar import ...`.

gotcha In Jupyter notebooks or environments that buffer `sys.stdout`, the progress bar output might appear mixed or delayed. ↓

fix To resolve this, explicitly flush stdout after updates or at critical points: `import sys; sys.stdout.flush()`.

gotcha When using Jetbrains IDEs (like PyCharm), especially for advanced features like `MultiBar` support or to prevent interleaved output between the progress bar (which often writes to stderr) and `print` statements (writing to stdout), you may need to enable 'Enable terminal in output console' in your run configuration. Alternatively, redirect the progress bar to `sys.stdout`. ↓

fix In PyCharm, check 'Enable terminal in output console'. For code, consider `ProgressBar(fd=sys.stdout)` to unify output streams.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.14s 18.8M

3.10 alpine (musl) - - 0.15s 18.8M

3.10 slim (glibc) wheel 1.7s 0.10s 19M

3.10 slim (glibc) - - 0.10s 19M

3.11 alpine (musl) wheel - 0.25s 20.9M

3.11 alpine (musl) - - 0.28s 20.9M

3.11 slim (glibc) wheel 1.8s 0.22s 21M

3.11 slim (glibc) - - 0.21s 21M

3.12 alpine (musl) wheel - 0.47s 12.7M

3.12 alpine (musl) - - 0.48s 12.7M

3.12 slim (glibc) wheel 1.6s 0.43s 13M

3.12 slim (glibc) - - 0.44s 13M

3.13 alpine (musl) wheel - 0.47s 12.4M

3.13 alpine (musl) - - 0.49s 12.3M

3.13 slim (glibc) wheel 1.7s 0.43s 13M

3.13 slim (glibc) - - 0.44s 13M

3.9 alpine (musl) wheel - 0.13s 18.3M

3.9 alpine (musl) - - 0.14s 18.3M

3.9 slim (glibc) wheel 1.9s 0.12s 19M

3.9 slim (glibc) - - 0.13s 19M

Imports

ProgressBar
wrong
```
from progressbar2 import ProgressBar
```
correct
```
from progressbar import ProgressBar
```
Despite the package being named `progressbar2`, the primary module to import is `progressbar`.
widgets
```
from progressbar import Bar, Percentage, ETA
```
Commonly imported widgets include `Bar`, `Percentage`, `ETA`, `Timer`, `AdaptiveETA`, etc.
progressbar
```
import progressbar
```
The top-level `progressbar` module can be imported directly, often used when wrapping iterables like `progressbar.progressbar(range(100))`.

Quickstart last tested: 2026-04-24

This example demonstrates basic usage with the context manager pattern. It initializes a progress bar with a maximum value and updates it in a loop. The bar automatically handles starting and finishing.

import time
import progressbar

MAX_VALUE = 100

with progressbar.ProgressBar(max_value=MAX_VALUE) as bar:
    for i in range(MAX_VALUE):
        # Simulate a task
        time.sleep(0.02)
        bar.update(i + 1)

print("Task completed!")