Install & Compatibility
Where this runs
tested against v4.36.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.506s · 33.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.0s · import 0.476s · 36MB
32MB installed
● package 32MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TeleBot
✓ from telebot import TeleBot
✗ import telebot
This quickstart sets up a basic synchronous 'EchoBot' that replies to /start, /help, and any other text message by echoing the input. Ensure you replace 'YOUR_BOT_TOKEN_HERE' or set the `TELEGRAM_BOT_TOKEN` environment variable with the token obtained from @BotFather. The bot uses `infinity_polling()` to continuously check for new messages.
import os
import telebot
API_TOKEN = os.environ.get('TELEGRAM_BOT_TOKEN', 'YOUR_BOT_TOKEN_HERE')
if not API_TOKEN or API_TOKEN == 'YOUR_BOT_TOKEN_HERE':
print("Warning: TELEGRAM_BOT_TOKEN environment variable not set or placeholder used. \n"\
"Please obtain a token from @BotFather on Telegram and set it.")
exit(1)
bot = telebot.TeleBot(API_TOKEN)
@bot.message_handler(commands=['start', 'help'])
def send_welcome(message):
bot.reply_to(message, "Hi there, I am an EchoBot. I will echo your messages.")
@bot.message_handler(func=lambda message: True)
def echo_message(message):
bot.reply_to(message, message.text)
print("Bot started polling...")
bot.infinity_polling()
Debug
Known issues
breakingMajor changes in the official Telegram Bot API, while often accommodated by library updates, can sometimes introduce breaking changes requiring code migration. Always review the `pyTelegramBotAPI` changelog and Telegram Bot API release notes when upgrading, especially across significant version bumps.fixConsult the official pyTelegramBotAPI GitHub releases and Telegram Bot API documentation for migration guides. Update your bot's code to align with new API specifications.
affects: All versions, dependent on Telegram Bot API changes
deprecatedThe `reply_to_message_id`, `allow_sending_without_reply`, and `disable_web_page_preview` parameters in `bot.send_message()` and similar methods have been deprecated by Telegram. While they might still function, it's recommended to use newer alternatives for reply parameters and link previews.fixFor replies, use `reply_parameters` instead of `reply_to_message_id`. For web page previews, refer to the current Telegram Bot API documentation for `link_preview_options`.
affects: 4.26.0 and higher
gotchaThe library offers both synchronous (`telebot.TeleBot`) and asynchronous (`telebot.async_telebot.AsyncTeleBot`) implementations. Mixing them incorrectly or using `TeleBot` with long-running operations in handlers without threading can block your bot. `TeleBot`'s `infinity_polling()` is synchronous, while `AsyncTeleBot` typically uses `asyncio.run(bot.polling())`.fixFor synchronous bots, ensure handlers are fast or delegate long tasks to separate threads/processes (e.g., by initializing `TeleBot(threaded=True)`). For I/O-bound tasks and better scalability, consider using `AsyncTeleBot` and `async`/`await` patterns consistently throughout your bot's logic.
affects: All 4.x versions
gotchaThe `Message` object received by handlers has its `from` attribute renamed to `from_user` (`message.from_user`) to avoid conflict with Python's `from` keyword. Directly accessing `message.from` will raise an `AttributeError`.fixAlways use `message.from_user` to access information about the user who sent the message.
affects: All 4.x versions
Upgrade
Version history
4.36.1latest on PyPI · released Aug 13, 2026
Audit
Dependencies
No dependency data recorded yet.