Бот на aiogram 3: установка, первый Telegram-бот на Python и запуск на сервере

aiogram — асинхронный фреймворк на Python для Telegram Bot API. Чтобы собрать на нём бота, поставьте Python 3.10 или новее, выполните pip install -U aiogram, получите токен у @BotFather и запустите скрипт, где Dispatcher вызывает start_polling. Ниже рабочий код третьей версии: команда /start, эхо, inline-кнопки, анкета на машине состояний и запуск на сервере.

Если асинхронный код пока пугает, начните с бота на pyTelegramBotAPI: там те же шаги на синхронной библиотеке. aiogram берут, когда бот обслуживает много людей сразу и не должен ждать, пока Telegram ответит на каждый запрос.

Рекомендуем курсы по Python

• Skillbox10 ★Профессия «Python-разработчик»157 335 ₽10 месяцев
• Нетология9.8 ★Fullstack-разработчик на Python137 000 ₽21 месяц
• GeekBrains9.7 ★ДО Профессия Python-разработчик149 001 ₽10 месяцев
• SkillFactory9.7 ★Профессия Python-разработчик154 044 ₽10 месяцев
• Академия Синергия9.7 ★Python-разработчик + ИИ77 900 ₽6 месяцев
• Эдюсон9.6 ★Python-разработчик119 892 ₽9 месяцев

Все 568 курсов→

Что такое aiogram и какая версия актуальна

Библиотека построена на asyncio и aiohttp. Пока один запрос к серверам Telegram в пути, бот уже обрабатывает следующее сообщение. По странице пакета на PyPI, версия 3.31.0 вышла 26 августа 2026 года и работает на Python от 3.10 до 3.14.

Главное, что надо знать до первой строки кода: aiogram 2 и aiogram 3 несовместимы. Примеры с executor и @dp.message_handler, которые ещё встречаются в учебных материалах, написаны под вторую версию и на третьей падают сразу.

Полный список переименований есть в руководстве по переходу с 2.x на 3.x из официальной документации.

Как установить aiogram и получить токен

1. Проверьте версию Python: python3 --version на macOS и Linux, python --version на Windows. Нужна 3.10 или выше. Если Python нет, поставьте его по инструкции для Windows, macOS и Linux.
2. Создайте папку проекта и виртуальное окружение, чтобы библиотеки бота не смешались с системными.
3. Активируйте окружение и поставьте библиотеку из PyPI.

mkdir tgbot
cd tgbot
python3 -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -U aiogram

Проверьте, что библиотека встала:

python -c "import aiogram; print(aiogram.__version__)"
3.31.0

Команда pip install -U aiogram взята из раздела Installation документации. Ключ -U обновит библиотеку, если старая версия уже стоит. Для хранения анкет в Redis понадобится дополнение: pip install -U "aiogram[redis]".

Если пишете в редакторе кода, выберите в нём интерпретатор из папки .venv. Иначе запуск из редактора закончится ошибкой ModuleNotFoundError, хотя в терминале всё работает. Как это сделать в одной из популярных сред, показано в настройке VS Code для Python.

Токен у BotFather и где его хранить

1. Найдите в Telegram аккаунт @BotFather и отправьте ему /newbot.
2. Придумайте имя бота и username. Username должен заканчиваться на bot.
3. BotFather пришлёт токен вида 123456789:AAH…. Это ключ от бота: кто его знает, тот и управляет ботом.

Поэтому токен не пишут в код, особенно если код уйдёт на GitHub. Его кладут в переменную окружения, а скрипт читает её при старте:

export BOT_TOKEN="123456789:AAH..."      # macOS и Linux
$env:BOT_TOKEN="123456789:AAH..."        # Windows, PowerShell

Переменная живёт, пока открыт терминал. Закрыли окно, и перед запуском её придётся задать снова.

Первый бот на aiogram 3: команда /start и эхо

Создайте файл bot.py. Этот бот здоровается по имени на /start и повторяет любой текст:

import asyncio
import logging
import os

from aiogram import Bot, Dispatcher, F, Router
from aiogram.filters import CommandStart
from aiogram.types import Message

router = Router()


@router.message(CommandStart())
async def cmd_start(message: Message) -> None:
    await message.answer(
        f"Привет, {message.from_user.first_name}! Пришлите текст, и я его повторю. "
        "Меню с кнопками: /menu"
    )


@router.message(F.text)
async def echo(message: Message) -> None:
    await message.answer(message.text)


async def main() -> None:
    logging.basicConfig(level=logging.INFO)
    bot = Bot(token=os.environ["BOT_TOKEN"])
    dp = Dispatcher()
    dp.include_router(router)
    await dp.start_polling(bot)


if __name__ == "__main__":
    asyncio.run(main())

Запустите его командой python bot.py. В терминале появится строка INFO:aiogram.dispatcher:Start polling, и бот начнёт отвечать. Остановить его можно сочетанием Ctrl+C.

Что здесь происходит:

• Router собирает обработчики. В маленьком боте он один, в большом их делят по файлам: анкета отдельно, админка отдельно.
• CommandStart() ловит /start, а F.text ловит любое текстовое сообщение.
• message.answer() отправляет ответ в тот же чат. Перед ним стоит await, потому что метод асинхронный. Если async и await пока не складываются в картину, посмотрите курсы по асинхронному программированию.
• Имя в приветствии подставляет f-строка: всё, что стоит в фигурных скобках, Python вычисляет и вставляет в текст.
• dp.start_polling(bot) раз за разом спрашивает у Telegram новые сообщения. Пока скрипт работает, бот на связи.

Порядок обработчиков важен. Сообщение уходит первому подходящему обработчику, поэтому эхо стоит последним. Поднимите его выше, и бот начнёт повторять даже команды. Если функции и декораторы пока читаются с трудом, загляните в разбор функций в Python.

CheckroiПодборка курсов по Python567 курсов • 51 школаСравните цены, школы, программу и найдите выгодные предложения по обучениюСравнить→

Кнопки и фото в боте на aiogram

Inline-кнопки под сообщением

Кнопки под сообщением собирают через InlineKeyboardBuilder. Добавьте в bot.py импорты и два обработчика нажатий. Код ставится выше эха:

from datetime import datetime

from aiogram.filters import Command
from aiogram.types import CallbackQuery
from aiogram.utils.keyboard import InlineKeyboardBuilder


@router.message(Command("menu"))
async def cmd_menu(message: Message) -> None:
    builder = InlineKeyboardBuilder()
    builder.button(text="Который час", callback_data="time")
    builder.button(text="Убрать кнопки", callback_data="hide")
    await message.answer("Что сделать?", reply_markup=builder.as_markup())


@router.callback_query(F.data == "time")
async def on_time(callback: CallbackQuery) -> None:
    await callback.answer(datetime.now().strftime("%H:%M"), show_alert=True)


@router.callback_query(F.data == "hide")
async def on_hide(callback: CallbackQuery) -> None:
    await callback.message.edit_reply_markup(reply_markup=None)
    await callback.answer()

Как это работает:

• При нажатии бот получает не сообщение, а CallbackQuery со строкой из callback_data. По описанию InlineKeyboardButton, в ней от 1 до 64 байт, поэтому туда кладут короткий код действия, а не данные.
• show_alert=True показывает ответ всплывающим окном. Без этого флага текст всплывёт уведомлением вверху чата.
• edit_reply_markup(reply_markup=None) убирает клавиатуру из сообщения.
• Обе кнопки встанут в один ряд. Чтобы разложить их по одной в строке, вызовите builder.adjust(1) перед as_markup().

callback.answer() вызывайте всегда, даже если отвечать нечего. В описании CallbackQuery сказано: после нажатия клиент Telegram показывает индикатор загрузки, пока бот не вызовет AnswerCallbackQuery.

Клавиатура под полем ввода и отправка фото

Inline-кнопки висят под конкретным сообщением. Есть второй вид: клавиатура вместо обычной, под полем ввода. Нажатие на такую кнопку просто отправляет её текст в чат, поэтому ловят его обычным фильтром по тексту.

from aiogram.types import FSInputFile, ReplyKeyboardRemove
from aiogram.utils.keyboard import ReplyKeyboardBuilder


@router.message(Command("photo"))
async def cmd_photo(message: Message) -> None:
    await message.answer_photo(FSInputFile("cat.jpg"), caption="Это кот")


@router.message(Command("ask"))
async def cmd_ask(message: Message) -> None:
    builder = ReplyKeyboardBuilder()
    builder.button(text="Да")
    builder.button(text="Нет")
    await message.answer(
        "Подписаться на рассылку?",
        reply_markup=builder.as_markup(resize_keyboard=True, one_time_keyboard=True),
    )


@router.message(F.text.in_({"Да", "Нет"}))
async def on_answer(message: Message) -> None:
    await message.answer(f"Ответ принят: {message.text}", reply_markup=ReplyKeyboardRemove())

• FSInputFile отправляет файл с диска, путь считается от папки, откуда запущен скрипт, как и при открытии файла через open(). Для документа то же самое делает answer_document.
• resize_keyboard=True подгоняет высоту клавиатуры под число рядов, без него она занимает столько же места, сколько обычная. one_time_keyboard=True прячет её после нажатия, вернуть можно значком в поле ввода. Оба флага описаны на странице ReplyKeyboardMarkup.
• ReplyKeyboardRemove() убирает клавиатуру совсем, когда ответ получен.

Эти обработчики тоже ставятся выше эха, иначе «Да» и «Нет» бот просто повторит.

Анкета на машине состояний (FSM)

Когда бот задаёт вопросы по очереди, ему нужно помнить, на каком шаге человек. Для этого в aiogram есть машина состояний. Пример спрашивает имя и город:

from aiogram.fsm.context import FSMContext
from aiogram.fsm.state import State, StatesGroup


class Signup(StatesGroup):
    name = State()
    city = State()


@router.message(Command("signup"))
async def signup_start(message: Message, state: FSMContext) -> None:
    await state.set_state(Signup.name)
    await message.answer("Как вас зовут?")


@router.message(Signup.name, F.text)
async def signup_name(message: Message, state: FSMContext) -> None:
    await state.update_data(name=message.text)
    await state.set_state(Signup.city)
    await message.answer("Из какого вы города?")


@router.message(Signup.city, F.text)
async def signup_city(message: Message, state: FSMContext) -> None:
    data = await state.get_data()
    await state.clear()
    await message.answer(f"Записал: {data['name']}, {message.text}")

Signup — обычный класс Python, где каждое поле State() означает один шаг анкеты. Диалог выглядит так: /signup → «Как вас зовут?» → «Аня» → «Из какого вы города?» → «Казань» → «Записал: Аня, Казань». state.clear() в конце сбрасывает анкету, и следующее сообщение снова попадёт в эхо.

По умолчанию состояния лежат в памяти процесса. В разделе Storages про это хранилище прямо написано: для продакшена его не советуют, при перезапуске бота данные теряются. Для настоящего бота подключают Redis:

from aiogram.fsm.storage.redis import RedisStorage

dp = Dispatcher(storage=RedisStorage.from_url("redis://localhost:6379/0"))

CheckroiПодборка курсов по асинхронному программированию19 курсов • 9 школСравните цены, школы, программу и найдите выгодные предложения по обучениюСравнить→

Как запустить бота на сервере

Бот на вашем компьютере засыпает вместе с компьютером. Чтобы он отвечал круглосуточно, скрипт переносят на Linux-сервер. Получать сообщения можно двумя способами:

Для первого бота хватит polling. Скрипт оформляют службой systemd, чтобы он сам поднимался после сбоя и перезагрузки сервера. Файл службы и порядок команд разобраны в инструкции по боту на pyTelegramBotAPI, для aiogram меняется только одно. Наш код читает токен из переменной окружения, поэтому добавьте в раздел [Service] строку с файлом, где лежит токен:

[Service]
EnvironmentFile=/home/bot/tgbot/.env
ExecStart=/home/bot/tgbot/.venv/bin/python bot.py

В самом .env одна строка: BOT_TOKEN=123456789:AAH.... Права на файл лучше сразу ограничить: chmod 600 .env.

Канал основателя Checkroi Вани БуявцаЗабирайте промпты и обучение по нейросетям в моём Телеграм-каналеБольше 3 700 человек уже применяют Claude Code, ChatGPT и другие нейросети в работе, учёбе, бизнесе и жизниПерейти в канал→

Частые ошибки и что с ними делать

Большинство проблем с первым ботом укладывается в семь симптомов. Ищите в таблице текст из своего терминала:

С ModuleNotFoundError разбираются одинаково для любой библиотеки. Как выбрать правильное окружение, подробно рассказано в разборе той же ошибки в инструкции по установке PyGame.

Если бот молчит без всяких ошибок, проверьте две вещи. Отправляете ли вы текст, а не стикер: эхо ловит только F.text. И не стоит ли обработчик ниже эха.

CheckroiПодборка курсов по чат-ботам160 курсов • 42 школыСравните цены, школы, программу и найдите выгодные предложения по обучениюСравнить→

Где освоить Python, чтобы бот вырос

Эхо, кнопки и анкета закрывают первый вечер. Дальше идёт то, без чего не обходится настоящий бот: база данных, оплата, очереди, тесты, деплой без ручных шагов. Это обычная работа Python-разработчика. Про то, как выглядит профессия целиком, есть отдельный материал: кто такой разработчик чат-ботов.

Если хотите учиться с проверкой заданий и наставником, ниже курсы из каталога по Python:

Курс	Школа	Стоимость со скидкой	В рассрочку	Длитель­ность	Обзор курса от Checkroi
Профессия «Python-разработчик» Перейти на сайт курса	Skillbox	157 335 ₽	5987 ₽/мес.	10 месяцев	Обзор курса
Fullstack-разработчик на Python Перейти на сайт курса	Нетология	137 000 ₽	7125 ₽/мес.	21 месяц	Обзор курса
ДО Профессия Python-разработчик Перейти на сайт курса	GeekBrains	149 001 ₽	3167 ₽/мес.	10 месяцев	Обзор курса
Автоматизированное тестирование на Python Перейти на сайт курса	Skillbox	122 226 ₽	4108 ₽/мес.	9 месяцев	Обзор курса
Профессия Python-разработчик Перейти на сайт курса	SkillFactory	154 044 ₽	4279 ₽/мес.	10 месяцев	Обзор курса

• 

  Профессия «Python-разработчик»

  Skillbox157 335 ₽5987 ₽/мес10 месяцев
  Перейти на сайт курсаОбзор
• 

  Fullstack-разработчик на Python

  Нетология137 000 ₽7125 ₽/мес21 месяц
  Перейти на сайт курсаОбзор
• 

  ДО Профессия Python-разработчик

  GeekBrains149 001 ₽3167 ₽/мес10 месяцев
  Перейти на сайт курсаОбзор
• 

  Автоматизированное тестирование на Python

  Skillbox122 226 ₽4108 ₽/мес9 месяцев
  Перейти на сайт курсаОбзор
• 

  Профессия Python-разработчик

  SkillFactory154 044 ₽4279 ₽/мес10 месяцев
  Перейти на сайт курсаОбзор

Больше программ — в полном каталоге курсов по Python