Install & Compatibility
Where this runs
tested against v4.6.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.104s · 19.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.100s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ProgressBar
✓ from progressbar import ProgressBar
✗ from progressbar2 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))`.
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!")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'progressbar'
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`.
fixEnsure `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`.
TypeError: __init__() got an unexpected keyword argument 'max_value'
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`.
fixEnsure `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)`.
TypeError: 'module' object is not callable
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()`.
fixAlways 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(...)`.
AttributeError: module 'progressbar' has no attribute 'streams'
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`.
fixUninstall 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.
ValueError: Value X is out of range, should be between 0 and Y
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.
fixEnsure 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`.
Upgrade
Version history
4.6.0latest on PyPI · released Aug 14, 2026
Audit
Dependencies
requestsoptionalOptional dependency for examples involving network requests (e.g., file downloads).