Ошибка ImportError: cannot import name 'executor' после обновления aiogram — типичный признак того, что код написан под вторую версию библиотеки, а в окружении установилась третья. В aiogram 3.x полностью изменился API: исчез модуль executor, класс Bot перестал принимать parse_mode в конструкторе, а хендлеры регистрируются через роутеры. Самый быстрый способ вернуть работоспособность бота — откатить пакет до ветки 2.x.
В этой инструкции разберём, как проверить текущую версию, корректно удалить aiogram 3.x, установить нужный релиз второй ветки и зафиксировать зависимости, чтобы проблема не повторилась при следующем деплое.
Почему код ломается после обновления до aiogram 3
Третья версия aiogram — это фактически новая библиотека с несовместимым синтаксисом. Если проект писался по старым гайдам и использует конструкции вроде executor.start_polling(dp) или декоратор @dp.message_handler(), то на aiogram 3.x такой скрипт упадёт сразу при запуске.
Типичные симптомы несовместимости:
- 🔴
ImportError: cannot import name 'executor' from 'aiogram'; - 🟡
TypeError: Bot.__init__() got an unexpected keyword argument 'parse_mode'; - 🟠
AttributeError: 'Dispatcher' object has no attribute 'message_handler'; - 🔵 ошибки при импорте
aiogram.contrib.fsm_storage— этого модуля в третьей версии нет.
⚠️ Внимание: ветка aiogram 2.x больше не получает активных обновлений и новых функций Bot API. Откат — рабочее решение для поддержки существующего кода, но для новых проектов имеет смысл изучить миграцию на 3.x.
Шаг 1. Проверяем установленную версию
Перед откатом убедитесь, какая версия стоит в текущем окружении. Выполните в терминале с активированным виртуальным окружением:
pip show aiogramВ выводе найдите строку Version:. Если там 3.x.x, а код написан под вторую ветку — переходите к следующему шагу. Проверить версию можно и из самого Python:
python -c "import aiogram; print(aiogram.__version__)"Если команда падает с ошибкой импорта, это тоже косвенно подтверждает конфликт версий — библиотека установлена, но её API не соответствует ожиданиям кода.
Шаг 2. Удаляем aiogram 3.x и ставим вторую версию
Сначала удалите текущий пакет, чтобы исключить смешение файлов разных версий:
pip uninstall aiogram -yЗатем установите последний релиз второй ветки. На момент её поддержки финальной была линейка 2.25.x, но надёжнее указать диапазон, чтобы pip сам выбрал последний доступный релиз ветки 2:
pip install "aiogram<3"Либо зафиксируйте конкретную версию, если она известна и проверена в вашем проекте:
pip install aiogram==2.25.2☑️ Чек-лист отката aiogram
После установки снова выполните pip show aiogram — в строке версии должно быть значение, начинающееся с 2.. Это подтверждает успешный откат.
Шаг 3. Проверяем совместимость зависимостей
Откат aiogram может потянуть за собой конфликты с пакетами, которые были установлены под третью версию. Например, aiohttp новых релизов или сторонние библиотеки, собранные специально под aiogram 3.
Что проверить после отката:
- 🧩
pip check— покажет нарушенные зависимости в окружении; - 📦
pip list— сверьте версии aiohttp, pydantic и magic-filter с требованиями aiogram 2.x; - 🔁 сторонние модули (календари, пагинация, FSM-утилиты) — убедитесь, что они поддерживают вторую ветку.
Если pip check сообщает о конфликте, переустановите проблемный пакет с указанием совместимой версии. Для aiogram 2.x обычно требуется aiohttp ветки 3.x и pydantic первой версии — точные требования указаны в метаданных самого пакета aiogram, их можно посмотреть через pip show aiogram в строке Requires.
Шаг 4. Фиксируем версию в requirements.txt
Чтобы при следующем деплое или переустановке окружения pip снова не подтянул третью версию, зафиксируйте зависимость. Откройте requirements.txt и приведите строку с aiogram к одному из вариантов:
aiogram==2.25.2Или с ограничением сверху:
aiogram>=2.20,<3Первый вариант надёжнее: он гарантирует, что на всех машинах будет установлена одна и та же проверенная версия. Второй удобен, если вы хотите получать патч-обновления внутри второй ветки.
⚠️ Внимание: если в проекте используется pip install --upgrade в скриптах деплоя, без жёсткой фиксации версии aiogram обновится до 3.x автоматически, и бот снова упадёт. Всегда закрепляйте версию после отката.
Сравнение aiogram 2 и 3: что меняется при откате
Таблица ниже поможет понять, какие конструкции кода снова станут рабочими после отката на вторую ветку.
| Элемент | aiogram 2.x | aiogram 3.x |
|---|---|---|
| Запуск поллинга | executor.start_polling(dp) | await dp.start_polling(bot) |
| Хендлер сообщений | @dp.message_handler() | @router.message() |
| parse_mode | передаётся в Bot(token, parse_mode=...) | через DefaultBotProperties |
| Хранилища FSM | aiogram.contrib.fsm_storage | aiogram.fsm.storage |
| Фильтры | параметры декоратора (commands=, text=) | объекты фильтров (Command(), F.text) |
А если откат не помог и ошибки остались?
Проверьте, что запускаете скрипт тем же интерпретатором, в котором меняли пакет: команда python -m pip show aiogram покажет версию именно для этого Python. Также удалите кеш __pycache__ в папке проекта и перезапустите скрипт. Если ошибка сохраняется, убедитесь, что в проекте нет локальной папки с именем aiogram, которая могла бы перекрывать установленный пакет.
Альтернатива откату: миграция кода на aiogram 3
Откат — быстрое решение, но не единственное. Если проект активно развивается, имеет смысл переписать его под третью версию: она получает поддержку новых возможностей Telegram Bot API, тогда как вторая ветка остаётся в замороженном состоянии.
Миграция обычно включает замену executor на асинхронный запуск через asyncio, перенос хендлеров на роутеры и обновление фильтров. Для небольшого бота это работа на несколько часов, для крупного проекта с FSM и middleware — существенно дольше. Поэтому на практике многие комбинируют подходы: сначала откат для восстановления работоспособности, затем постепенный переход на 3.x в отдельной ветке репозитория.
⚠️ Внимание: не держите в одном окружении код, частично написанный под aiogram 2 и частично под aiogram 3, — синтаксис несовместим, и такой гибрид гарантированно не запустится. Выбирайте одну версию на проект.
Часто задаваемые вопросы
Как узнать, под какую версию aiogram написан мой код?
Ищите характерные конструкции: from aiogram import executor и @dp.message_handler() указывают на aiogram 2.x, а Router(), F.text и await dp.start_polling(bot) — на третью версию.
Можно ли установить aiogram 2 и 3 одновременно?
В одном окружении — нет, пакет один и версии заменяют друг друга. Но можно создать два отдельных виртуальных окружения: одно с aiogram 2.x для старого бота, другое с 3.x для нового проекта.
Какая версия aiogram 2.x последняя?
Финальные релизы второй ветки относятся к линейке 2.25.x. Чтобы получить последний доступный, используйте команду pip install "aiogram<3" — pip сам выберет максимальную версию ниже третьей.
После отката появилась ошибка с aiohttp. Что делать?
Возможная причина — слишком новая версия aiohttp, установленная под aiogram 3. Выполните pip check для диагностики и понизьте aiohttp до совместимой ветки 3.x, ориентируясь на требования из pip show aiogram.
Будет ли aiogram 2.x работать с новыми функциями Telegram?
Нет, вторая ветка не получает поддержку новых возможностей Bot API. Если боту нужны свежие функции Telegram, единственный путь — миграция кода на aiogram 3.x.