What to choose
aiogram vs python-telegram-bot: which should a beginner pick
In short
Both libraries work for a beginner: aiogram is handier if you learn from Russian-language material, and python-telegram-bot if you value thorough official documentation with examples. Both are asynchronous, both are actively developed and both cover everything a typical bot needs: commands, buttons, multi-step dialogs and webhooks. A third option, pyTelegramBotAPI (telebot), is the easiest to start with but offers less for complex dialogs. What matters more than the choice is learning from material written for the library's current version.
- aiogram 3 is not compatible with code written for aiogram 2: the dispatcher, filters and handler registration all changed.
- python-telegram-bot became fully asynchronous in version 20, and examples written for version 13 do not work with it.
- Current versions of aiogram and python-telegram-bot require Python 3.10 or newer.
- Multi-step dialogs in aiogram are built with its finite state machine (FSM), and in python-telegram-bot with ConversationHandler.
- The pyTelegramBotAPI package is installed under that name but imported in code as telebot.
When you write your first Telegram bot in Python, the question comes up almost right away: aiogram or python-telegram-bot. Chats can get heated about it, but for a beginner the difference is smaller than it looks. Both libraries are mature, both are maintained and both let you build a bot with commands, buttons, payments and multi-step dialogs.
The real differences are in code style, in the language most tutorials are written in, and in how dialogs that ask the user questions are built. There is also a third option, pyTelegramBotAPI, often called telebot after its module name, which is the easiest to start with. Below is how to choose without a holy war, and what you will need to put the bot online afterwards.
| Criterion | aiogram | python-telegram-bot | pyTelegramBotAPI (telebot) |
|---|---|---|---|
| Code style | asynchronous, async and await everywhere | asynchronous since version 20 | plain synchronous, with an async variant too |
| Learning curve | medium: you need async and routers | medium: you need async and handlers | low: a first bot in about ten lines |
| Learning material | huge Russian-speaking community, English docs | mostly English, very complete | lots of simple tutorials, some outdated |
| Official documentation | available, in English | very detailed, with a wiki and dozens of examples | brief, mostly examples |
| Multi-step dialogs | built-in FSM | ConversationHandler | has states, but simpler and more limited |
| Webhook support built in | yes | yes | yes |
| Main pitfall | aiogram 2 tutorials do not work in aiogram 3 | version 13 tutorials do not work in newer ones | code grows messy fast in bigger bots |
Pick aiogram if your learning material is in Russian#
aiogram has the largest Russian-speaking community: tutorials, walkthroughs, chats and ready-made examples, while its official docs are in English. The library is asynchronous and uses routers and filters, and multi-step dialogs such as a questionnaire are easy to build with its finite state machine. The learning curve is a bit steeper than telebot's because you have to get used to async and await. In return, the code scales well as the bot grows.
Pick python-telegram-bot if documentation matters most#
python-telegram-bot has some of the most thorough documentation among bot libraries: a wiki, dozens of examples and a guide to common mistakes, all in English. Since version 20 the library is fully asynchronous. Dialogs that ask the user questions are built with ConversationHandler, where every step is a separate state. If you are comfortable reading English and like learning from the source, it is a great choice.
Take telebot for a one-evening bot#
pyTelegramBotAPI lets you write an echo bot or a bot with a couple of commands in about ten lines, without async and without thinking about architecture. It is a good way to get a feel for how bots work. But once you add multi-step dialogs, user roles and a database, telebot code tends to grow faster, and many people switch to aiogram or python-telegram-bot at that point.
Check which version your tutorial targets#
The main reason code from the internet does not run is that the tutorial was written for an old version of the library. Code for aiogram 2 does not work in aiogram 3, and examples for python-telegram-bot 13 do not work in newer versions. Before copying an example, check its date and imports: if there is no async or await and you have a fresh library, look for another tutorial. Also pin the major version in requirements.txt, for example aiogram>=3,<4, so an update cannot break the bot.
Get the bot ready to publish#
For hosting, the choice of library does not matter: you need the same things either way. Put a requirements.txt with every library at the root of the project, otherwise the server will not install your dependencies. Do not hardcode the BotFather token; read it from an environment variable such as BOT_TOKEN. And start the bot from one obvious file like main.py or bot.py.
There is no right answer in the aiogram vs python-telegram-bot debate: choose by the language of the material you learn from and how much you value the docs, and take telebot for a very first try. After a month any of the three will feel familiar, and moving between them does not mean rewriting your logic from scratch. On Netrun all three are deployed the same way: upload the code folder with requirements.txt and add the token on the Secrets tab, where it is stored encrypted and passed in as an environment variable, and the platform installs the dependencies and starts the bot. Try Netrun.
Common questions
Which library is easiest to learn from scratch?
pyTelegramBotAPI is the easiest start: a bot with a couple of commands takes about ten lines without async. If you plan a bot with questionnaires and a database, learn aiogram or python-telegram-bot right away so you do not have to rewrite later. Either can be picked up in a few evenings.
Why does the code from my aiogram tutorial not work?
Most likely the tutorial was written for aiogram 2 and you have aiogram 3 installed. Version 3 creates the dispatcher and handlers differently, and the filters changed. Look for material made for aiogram 3, or pin the version the tutorial was written for in requirements.txt.
Can I move from one library to another?
Yes. The bot's logic, meaning texts, buttons and database work, carries over, and you rewrite the handlers and the startup. For a small bot that is an evening of work. For a big bot, switch gradually and test on a separate token.
Which library is faster?
For a typical bot you will not notice a difference: response time depends on the network and your own logic, not the library. The asynchronous aiogram and python-telegram-bot cope better with many simultaneous users, as long as your code has no long blocking calls. Any of the three is fine for a bot with a few hundred users.
Do I need my own server to run the bot around the clock?
No, you need a host that keeps the bot process running and restarts it after a failure. Renting a VPS, setting up systemd and keeping the system updated is optional. The choice of library has no effect on that.
Can I host a Telegram bot?
Yes. Upload the bot code and provide the token from BotFather (Telegram itself gives it to you when you create the bot) — Netrun starts the bot, and no VPS or manual setup is needed. On the free plan the bot runs for 3 hours so you can check everything; to keep it running around the clock, switch to the Pro plan.
Can I run a Python project — Django, Flask or FastAPI?
Yes. Put your dependencies in requirements.txt — Netrun detects Python and builds the project for you. Django, Flask and FastAPI are supported; the app should listen on the port from the environment variable, and keys and database access are set as secrets rather than in the code.
Where do I set tokens and other secret values?
Every project has a Secrets tab where you set the values from your code — for example the token from BotFather. We store them encrypted: you can see the variable names, but the values are shown to no one, including you.