Install & Compatibility
Where this runs
tested against v0.4.1 · 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.328s · 18.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.9s · import 0.298s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
tqdm
✓ from tqdm_loggable.auto import tqdm
✗ from tqdm.auto import tqdm
To leverage tqdm-loggable's features, you must import its `tqdm` wrapper instead of the original `tqdm.auto.tqdm` or `tqdm.tqdm`.
tqdm_logging
✓ from tqdm_loggable.tqdm_logging import tqdm_logging
Provides utilities for configuring tqdm-loggable's logging behavior, such as setting the log level and rate.
This quickstart demonstrates how to integrate `tqdm-loggable`. It configures standard Python logging, then uses `tqdm_loggable.auto.tqdm` to wrap an iterable. In an interactive terminal, this will show a normal progress bar. When run in a headless environment, or if `TQDM_LOGGABLE_FORCE=logging` is set, it will emit periodic log messages instead of an interactive bar, like 'Progress on: Processing items 10/20 rate:X it/s remaining:Y elapsed:Z'. The `set_log_rate` controls how frequently these log messages appear.
import datetime
import logging
import time
import os
from tqdm_loggable.auto import tqdm
from tqdm_loggable.tqdm_logging import tqdm_logging
# Configure basic logging
logger = logging.getLogger()
logger.setLevel(logging.INFO)
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
handler = logging.StreamHandler()
handler.setFormatter(formatter)
logger.addHandler(handler)
# Optional: Set tqdm-loggable's log level and update rate
tqdm_logging.set_level(logging.INFO)
tqdm_logging.set_log_rate(datetime.timedelta(seconds=2))
# You can force logging mode by setting an environment variable:
# os.environ['TQDM_LOGGABLE_FORCE'] = 'logging' # Forcing log output
# os.environ['TQDM_LOGGABLE_FORCE'] = 'stdout' # Forcing console bar
# os.environ['TQDM_LOGGABLE_FORCE'] = 'auto' # Restore auto-detection
print("Starting a simulated task...")
for i in tqdm(range(20), desc="Processing items", unit="item"):
time.sleep(0.5)
if i == 5:
logger.info("Mid-task progress report")
print("Task completed.")
Debug
Known issues
gotchaDo not confuse `tqdm-loggable` with `tqdm.contrib.logging`. They address different problems: `tqdm-loggable` converts progress bars to log messages in headless environments, while `tqdm.contrib.logging` redirects console log output to `tqdm.write()` to prevent interference with interactive bars.fixEnsure you understand the distinct use cases. Use `tqdm-loggable` for headless logging; use `tqdm.contrib.logging` within interactive sessions to manage log output alongside progress bars.
affects: All versions
gotchatqdm-loggable automatically detects interactive vs. non-interactive sessions to determine whether to show an interactive bar or log messages. This auto-detection can be overridden by setting the `TQDM_LOGGABLE_FORCE` environment variable to `stdout` (force interactive), `logging` (force log output), or `auto` (restore default behavior).fixIf unexpected behavior occurs, check or explicitly set the `TQDM_LOGGABLE_FORCE` environment variable to control the output mode.
affects: All versions
gotchaThe GitHub repository for `tqdm-loggable` indicates low activity. This means new feature requests or bug reports might experience slower response times.fixFor feature requests or pull requests, the maintainers suggest poking them on Discord first to ensure visibility.
affects: All versions
breakingWhen migrating from standard `tqdm` to `tqdm-loggable` in a headless environment, the expected output will change from no visible progress (or broken output) to periodic log messages. While this is the library's intended function, it is a significant behavioral change from `tqdm`'s default in non-interactive contexts.fixBe aware of this behavioral shift. The `set_log_rate` function in `tqdm_loggable.tqdm_logging` can be used to control the frequency of log updates to suit your monitoring needs.
affects: All versions where `tqdm` is used in headless mode
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'tqdm_loggable'
The 'tqdm-loggable' package has not been installed or is not accessible in the current Python environment.
fixpip install tqdm-loggable
ImportError: cannot import name 'TqdmLoggable' from 'tqdm_loggable'
The user attempted to import the main class with an incorrect capitalization or name. The actual class name is 'tqdm_loggable' (lowercase).
fixfrom tqdm_loggable import tqdm_loggable
TypeError: __init__() missing 1 required positional argument: 'iterable'
The 'tqdm_loggable' class, like 'tqdm.tqdm' which it extends, requires an iterable object as its first argument when instantiated.
fixfor item in tqdm_loggable(your_iterable):
NameError: name 'tqdm_loggable' is not defined
The 'tqdm_loggable' class was used in the code without being imported from its module first.
fixfrom tqdm_loggable import tqdm_loggable
Upgrade
Version history
0.4.1latest on PyPI · released Mar 16, 2026
Audit
Dependencies
tqdmrequiredCore functionality is built on top of tqdm.