pyTelegramBotAPI: a sync and async Python client for the Telegram Bot API

What pyTelegramBotAPI solves for Python bot authors

The Telegram Bot API is an HTTP interface. Calling it directly means building request URLs, serialising JSON, handling multipart uploads for files, and writing your own dispatch loop that turns an incoming update into the right function. pyTelegramBotAPI removes that layer. The README describes it as "a simple, but extensible Python implementation for the Telegram Bot API", and the design follows that description closely: one TeleBot class encapsulates the API calls, exposing methods named send_xyz such as send_message and send_document, plus a set of decorators for incoming updates. The target reader is a Python developer who already knows the Bot API and wants the transport handled. The README states the prerequisites plainly: an API token obtained from @BotFather, basic Python knowledge, and familiarity with the Telegram Bot API itself. This is not a framework that hides Telegram from you. Handler registration, filters and reply markup all map onto Telegram concepts, so the Bot API documentation remains your reference. The repository carries examples for callbacks, payments, polls, chat member changes, reactions, mini apps, middleware and multibot setups, which suggests the intended scope is broad rather than a single echo-bot demo.

Handlers, filters and the polling loop

The mechanism is decorator-based dispatch. You register a function with @bot.message_handler and pass filters; the README gives commands=['start', 'help'] and a lambda predicate as two forms. A decorated function may have any name but must take exactly one parameter, the message. Order matters: the README notes that all handlers are tested in the order in which they were declared, so a broad func=lambda m: True handler placed first will swallow everything after it. That is a real design constraint, not a footnote. It means the catch-all echo handler belongs at the bottom of the file, and it means debugging a bot that ignores a command usually starts with checking declaration order. The README documents separate handler families for edited messages, channel posts, edited channel posts, callback queries, shipping queries, pre-checkout queries, polls, poll answers, chat member updates and chat join requests. Inline mode has its own inline and chosen-inline handlers. Beyond the decorators, the README lists middleware handlers, custom filters and reply markup as additional features. The dispatch loop itself is started by bot.infinity_polling(), which the README uses to close the first example. An asynchronous variant, AsyncTeleBot, is documented separately, and the README also covers webhooks as an alternative to polling.

Installing pyTelegramBotAPI and running a first bot

Installation is a single pip command. The README gives two routes and recommends the first.

pip install pyTelegramBotAPI

The alternative is installing from source with git: pip install git+https://github.com/eternnoir/pyTelegramBotAPI.git. The README also suggests keeping the package current with pip install pytelegrambotapi --upgrade. Python support is stated as 3.10 through 3.14 plus PyPy 3, and pyproject.toml sets requires-python to >=3.10. The runtime dependencies listed there are requests and aiohttp.

For a first bot, create echo_bot.py. The README's example constructs the client with an explicit parse_mode argument:

import telebot

bot = telebot.TeleBot("TOKEN", parse_mode=None)  # HTML or MARKDOWN

Replace TOKEN with the value from @BotFather. Then register handlers. The README's first handler replies to /start and /help:

@bot.message_handler(commands=['start', 'help'])
def send_welcome(message):
    bot.reply_to(message, "Howdy, how are you doing?")

A second handler echoes everything else, using a lambda that always returns True:

@bot.message_handler(func=lambda message: True)
def echo_all(message):
    bot.reply_to(message, message.text)

Finally, start the loop:

bot.infinity_polling()

Run python echo_bot.py with the process still attached to a terminal. The expected result is that /start and /help produce the static reply and any other text message is echoed back to the sender. Because handlers run in declaration order, the echo handler must come after the command handler if you want commands to keep working.

Where the polling model and the licence bite

The first limitation is structural. infinity_polling keeps a long-running process that repeatedly asks Telegram for updates. The README offers webhooks as the alternative, but the two are different deployment shapes: polling needs no public endpoint and survives restarts by resuming, while webhooks need a reachable HTTPS address and a server that can pass updates into the library. A serverless or short-lived execution environment fits neither without extra work. The second limitation is state. The README documents custom_states as an example file, and the repository ships examples/custom_states.py, but state storage is not a first-class feature of the library the way it is in some competing frameworks. You supply the store. The optional dependencies in pyproject.toml tell the same story: redis>=3.4.1 is an extra you install yourself, not a default. The third is licensing. pyproject.toml declares license = {text = "GPL2"} and the classifier GNU General Public License v2 (GPLv2). If you plan to distribute a closed-source product that links this library, GPL-2.0 is a constraint you need to understand before writing code, not after. The README does not discuss licence implications for downstream users, so that question belongs with your own legal review. Finally, the README itself flags an "API conformance limitations" section, which is the honest place to check whether a specific Bot API feature you need is fully covered.

How pyTelegramBotAPI differs from python-telegram-bot and aiogram

The three libraries solve the same problem with different shapes. python-telegram-bot is the other long-standing option; the searches people run around this project pair the two constantly. The practical distinction is API style and async posture. pyTelegramBotAPI's README presents a synchronous TeleBot first, with AsyncTeleBot documented as a separate class, so a synchronous bot is the default path. Frameworks built async-first make you write async from the start. That difference shows up in your handler signatures and in which HTTP dependency does the work: pyTelegramBotAPI lists both requests and aiohttp in pyproject.toml because it supports both modes. aiogram is the third name that appears in comparisons, and it is the one usually chosen by teams that want an async framework with its own router and state machinery rather than a client that maps closely onto the raw Bot API. The trade-off is not quality. pyTelegramBotAPI keeps the Telegram Bot API visible: send_xyz methods, decorators with filters, and types that mirror the official documentation. If you want the framework to own more of your application structure, the other two give you more of that. If you want a thin, sync-friendly client, this one is the smaller step.

Maintenance, releases and upgrade cost

The repository is not archived and the last push was on 2026-09-21, the same day as release 4.37.0. The three most recent releases track Telegram Bot API versions directly: 4.35.0 for Bot API 10.1, 4.36.0 for 10.2 and 4.37.0 for 10.3. That naming convention is the maintenance story. When Telegram ships a Bot API update, this library ships a version that claims support for it, and the README states the supported Bot API version at the top. The upgrade cost follows from that: each release can add new types and methods, and the README's own advice is to update regularly with pip install pytelegrambotapi --upgrade. There is no documented deprecation policy in the README, and no rollback procedure is described, so pinning a version in your requirements file is the only mechanism available for controlling what you run. On licensing, the package metadata declares GPL-2.0. That matters more here than for a permissively licensed client because of how the GPL treats distributed derivative works. Whether your use counts as distribution is a legal question, and the README does not answer it. What the repository does give you is the licence text at the top level, in LICENSE, so the terms are available without leaving the project.

Editorial conclusion

Adopt pyTelegramBotAPI if you want a single TeleBot class, decorator handlers and the choice between polling and webhooks without rewriting your code, and if GPL-2.0 fits how you ship. Do not adopt it if you need a permissive licence, or if you want the framework to schedule and persist your own state for you. Verify first that your installed version matches the Bot API version you target, since the README lists 10.3 for release 4.37.0.

Frequently asked questions

Official sources

1. eternnoir/pyTelegramBotAPI on GitHub
2. Issues
3. License: GPL-2.0
4. README
5. Releases