tqdm progress bars in Telegram, Discord and Slack

Runpeek: a live link plus Discord or Slack alerts

Runpeek's tqdm-live package keeps tqdm's terminal bar and adds a live link instead of a chat message. Import tqdm from tqdm_live, call tqdm_live.start_run("name"), and every bar in the script shows on one link with the run's status, duration and host. Nobody needs an account to watch. Start the script with tqdml run -- python train.py instead and the link also streams its printed output, with no code changes.

Alerts go to a webhook URL, so there's no bot to create: tqdm_live.notify(url) sends a message when the run finishes or fails, and stall_after_minutes=15 adds one when no update arrives for 15 minutes. Discord and Slack webhook URLs get a formatted chat message, and any other webhook URL gets a JSON POST.

Call notify() after start_run(), because alerts belong to a run and notify() returns False without one. You can add up to 5 webhooks per run, or list them in TQDMLIVE_NOTIFY so every run picks them up, tqdml run included.

How the chat integrations work

When you import tqdm or trange from tqdm.contrib.telegram, tqdm.contrib.discord or tqdm.contrib.slack, you get a drop-in class that still draws the normal progress bar in your terminal. When the bar is created, it also posts a single message to your chat app, and then it edits that same message in place as the bar moves forward.

To keep network calls from slowing down your loop, a background worker handles the edits. That worker holds at most one pending edit in its queue and drops any older ones that haven't been sent yet, so a fast loop won't pile up hundreds of outdated requests.

All three modules live in tqdm.contrib, which the tqdm README lists as experimental modules.

Telegram

Telegram is usually the fastest of the three to set up. You need the telegram extra, which pulls in requests and envwrap:

• Run pip install "tqdm[telegram]" in your environment.
• Message @BotFather in Telegram to create a new bot and copy its token.
• Add the bot to a chat and send it a message such as /start, then open https://api.telegram.org/bot<token>/getUpdates in a browser (with your bot token in place of <token>) and copy the chat_id from the response.
• Import tqdm or trange from tqdm.contrib.telegram and pass both token and chat_id, or set TQDM_TELEGRAM_TOKEN and TQDM_TELEGRAM_CHAT_ID so you don't have to pass them in code.

# export TQDM_TELEGRAM_TOKEN="123456:ABC-your-bot-token"
# export TQDM_TELEGRAM_CHAT_ID="987654321"
from time import sleep
from tqdm.contrib.telegram import tqdm

for item in tqdm(range(200), desc="training"):
    sleep(0.5)

Discord

tqdm.contrib.discord talks to Discord's REST API v10 using requests, which means it requires a bot token and will not work with a Discord webhook URL.

• Install the extra with pip install "tqdm[discord]".
• Create a Discord bot that isn't public and only has permission to send messages, and invite it to the channel where you want the bar to show up.
• Pass token and channel_id to tqdm(), or export TQDM_DISCORD_TOKEN and TQDM_DISCORD_CHANNEL_ID in your shell before running your script.

from time import sleep
from tqdm.contrib.discord import tqdm

for item in tqdm(range(200), token="your-bot-token", channel_id="123456789012345678"):
    sleep(0.5)

Slack

The Slack integration relies on slack_sdk under the hood and requires a Slack app rather than an incoming webhook.

• Run pip install "tqdm[slack]" to get tqdm with slack_sdk and envwrap.
• Create a Slack app, grant it the chat:write scope, install it to your workspace, and invite the app into the channel you want to post in.
• Call tqdm(iterable, token="...", channel="...") from tqdm.contrib.slack, or set the TQDM_SLACK_TOKEN and TQDM_SLACK_CHANNEL environment variables.

Because Slack is strict about how often you edit a message, the tqdm Slack class forces mininterval to at least 1.5 seconds, even if you pass a smaller value.

from time import sleep
from tqdm.contrib.slack import tqdm

for item in tqdm(range(200), token="xoxb-your-bot-token", channel="C0123456789"):
    sleep(0.5)

Credentials and environment variables

Runpeek's link needs no credentials, and its alerts only need a webhook URL. Bot tokens are secrets, so keep them in environment variables instead of hardcoding them in your scripts. If the matching environment variables are set, you can call tqdm(iterable) without passing credentials in Python at all.

Limits of the tqdm.contrib bots

Because these modules only edit a single status message, they don't send a separate "finished" or "failed" message. When your script ends normally or crashes partway through, the chat message just stops changing, and there is no alert when a script hangs either. With leave=False, the Discord class deletes the message when the bar closes. The Telegram class is meant to as well, but a bug in tqdm 4.70.1 (its delete URL is never filled in) leaves the message in place.

You can also run into API rate limits if you create bars too quickly. If creating the initial chat message hits an HTTP 429 response on Telegram or Discord, tqdm prints a warning:

Creation rate limit: try increasing mininterval.

Test your credentials on a short loop before a long run. In our test with tqdm 4.70.1, a wrong Telegram or Discord token printed a 401 Client Error: Unauthorized line and then stopped the loop with UnboundLocalError: cannot access local variable 'req'; tqdm issue #1812 reports the same error for connection failures. A wrong Slack token printed invalid_auth and the loop carried on.