Что выбрать
aiogram или python-telegram-bot: какую библиотеку выбрать новичку
Коротко
Новичку подойдут обе библиотеки: aiogram удобнее, если вы учитесь по материалам на русском, а python-telegram-bot — если вам важна подробная официальная документация с примерами. Обе асинхронные, обе активно развиваются и умеют всё, что нужно обычному боту: команды, кнопки, сценарии из нескольких шагов, webhook. Третий вариант, pyTelegramBotAPI (telebot), проще всех на старте, но для сложных сценариев его возможностей меньше. Важнее выбора библиотеки — учиться по материалам для её актуальной версии.
- aiogram третьей версии несовместим с кодом для aiogram 2: изменились диспетчер, фильтры и регистрация обработчиков.
- python-telegram-bot стал полностью асинхронным начиная с 20-й версии, и примеры для 13-й версии с ним не работают.
- Свежие версии aiogram и python-telegram-bot требуют Python 3.10 или новее.
- Сценарии из нескольких шагов в aiogram делаются встроенной машиной состояний FSM, в python-telegram-bot — через ConversationHandler.
- Пакет pyTelegramBotAPI устанавливается под этим именем, а в коде импортируется как telebot.
Если вы пишете первого Telegram-бота на Python, почти сразу встаёт вопрос: aiogram или python-telegram-bot. В чатах по этому поводу бывают жаркие споры, но для новичка разница меньше, чем кажется. Обе библиотеки зрелые, обе поддерживаются и обе позволяют сделать бота с командами, кнопками, оплатой и сценариями из нескольких шагов.
Реальные различия — в стиле кода, в том, на каком языке написаны учебники, и в том, как устроены сценарии с вопросами пользователю. Есть и третий вариант — pyTelegramBotAPI, его часто называют telebot по имени модуля: он проще всех на старте. Ниже — как выбрать без религиозных войн и что понадобится, чтобы потом опубликовать бота.
| Критерий | aiogram | python-telegram-bot | pyTelegramBotAPI (telebot) |
|---|---|---|---|
| Стиль кода | асинхронный, async и await везде | асинхронный с 20-й версии | обычный синхронный, есть и асинхронный вариант |
| Порог входа | средний: нужно понять async и роутеры | средний: нужно понять async и обработчики | низкий: первый бот в десяток строк |
| Материалы на русском | больше всего: учебники, разборы, чаты сообщества | немного, основное на английском | много простых уроков, часть устарела |
| Официальная документация | есть, на английском | очень подробная, с вики и десятками примеров | краткая, в основном примеры |
| Сценарии из нескольких шагов | встроенная машина состояний FSM | ConversationHandler | есть состояния, но проще и беднее |
| Webhook из коробки | да | да | да |
| Главная ловушка | уроки для aiogram 2 не работают в aiogram 3 | уроки для 13-й версии не работают в новых | на сложных ботах код быстро разрастается |
Выберите aiogram, если учитесь по материалам на русском#
У aiogram самое большое русскоязычное сообщество: учебники, разборы, чаты, готовые примеры. Библиотека асинхронная, использует роутеры и фильтры, а сценарии из нескольких шагов, например анкету, удобно делать встроенной машиной состояний FSM. Порог входа чуть выше, чем у telebot, потому что придётся привыкнуть к async и await. Зато код хорошо растёт вместе с ботом.
Выберите python-telegram-bot, если вам важна документация#
У python-telegram-bot одна из самых подробных документаций среди библиотек для ботов: вики, десятки примеров, разбор частых ошибок, всё на английском. С 20-й версии библиотека полностью асинхронная. Сценарии с вопросами пользователю собираются через ConversationHandler, где каждый шаг — отдельное состояние. Если вы спокойно читаете на английском и любите разбираться по первоисточнику, это хороший выбор.
Возьмите telebot, если нужен бот на один вечер#
pyTelegramBotAPI позволяет написать бота-эхо или бота с парой команд в десяток строк, без async и без понимания архитектуры. Это хороший старт, чтобы почувствовать, как работают боты. Но когда появятся многошаговые сценарии, роли пользователей и база данных, код на telebot обычно разрастается быстрее, и многие на этом этапе переходят на aiogram или python-telegram-bot.
Проверьте версию в уроке, по которому учитесь#
Главная причина, по которой код из интернета не запускается, — урок написан для старой версии библиотеки. Код для aiogram 2 не работает в aiogram 3, а примеры для python-telegram-bot 13-й версии не работают в новых. Перед тем как копировать пример, посмотрите на дату и на импорты: если в уроке нет async и await, а у вас свежая библиотека, ищите другой урок. И закрепите мажорную версию в requirements.txt, например aiogram>=3,<4, чтобы обновление не сломало бота.
Подготовьте бота к публикации#
Для хостинга выбор библиотеки не важен: нужны одни и те же вещи. В корне проекта должен лежать requirements.txt со всеми библиотеками, иначе сервер не установит зависимости. Токен от BotFather не пишите в код строкой, а читайте из переменной окружения, например BOT_TOKEN. И запускайте бота одним понятным файлом вроде main.py или bot.py.
Правильного ответа в споре aiogram против python-telegram-bot нет: выбирайте по языку материалов и удобству документации, а telebot берите для самого первого знакомства. Через месяц работы любой из трёх вариантов будет казаться понятным, а перейти между ними можно без переписывания логики с нуля. В Netrun все три библиотеки публикуются одинаково: загрузите папку с кодом и requirements.txt, укажите токен во вкладке «Секреты», где он хранится зашифрованным и попадает в переменные окружения, — платформа сама поставит зависимости и запустит бота. Попробовать Netrun.
Частые вопросы
Какую библиотеку проще всего освоить с нуля?
Проще всего стартовать на pyTelegramBotAPI: бот с парой команд пишется в десяток строк без async. Если вы планируете бота с анкетами и базой данных, лучше сразу учить aiogram или python-telegram-bot, чтобы не переписывать позже. Обе осваиваются за несколько вечеров.
Почему код из урока по aiogram не работает?
Скорее всего, урок написан для aiogram 2, а у вас установлен aiogram 3. В третьей версии по-другому создаются диспетчер и обработчики, поменялись фильтры. Ищите материалы именно для aiogram 3 или закрепите в requirements.txt ту версию, под которую написан урок.
Можно ли перейти с одной библиотеки на другую?
Да, логика бота — тексты, кнопки, работа с базой — переносится, переписывать приходится обработчики и запуск. Для небольшого бота это работа на вечер. Если бот большой, переход лучше делать постепенно и на тестовом токене.
Какая библиотека быстрее работает?
Для обычного бота разницы не заметно: время ответа определяет скорость сети и вашей логики, а не библиотека. Асинхронные aiogram и python-telegram-bot лучше справляются со множеством одновременных пользователей, если в коде нет долгих блокирующих вызовов. Для бота на сотни пользователей подойдёт любая из трёх.
Нужен ли свой сервер, чтобы бот работал круглосуточно?
Нет, достаточно хостинга, который держит процесс бота запущенным и перезапускает его после сбоя. Арендовать VPS, настраивать systemd и следить за обновлениями системы для этого не обязательно. Выбор библиотеки на это не влияет.
Можно ли разместить Telegram-бота?
Да. Загрузите код бота и укажите токен от BotFather (его выдаёт сам Telegram при создании бота) — Netrun запустит бота, VPS и ручная настройка не нужны. На бесплатном тарифе бот работает 3 часа, чтобы вы всё проверили; чтобы он работал круглосуточно, подключите тариф Pro.
Можно ли запустить проект на Python — Django, Flask или FastAPI?
Да. Положите зависимости в requirements.txt — Netrun определит Python и соберёт проект сам. Django, Flask и FastAPI поддерживаются; приложение должно слушать порт из переменной окружения, а ключи и доступ к базе задаются как секреты, а не в коде.
Где указать токены и другие секретные значения?
В проекте есть вкладка «Секреты» — там задаются значения из кода, например токен от BotFather. Мы храним их в зашифрованном виде: названия переменных вы видите, сами значения не показываем никому, включая вас.