aiogram
raw JSON → 3.27.0 verified Wed May 13 auth: no python
aiogram is a modern and fully asynchronous framework for the Telegram Bot API, built on `asyncio`. It provides a high-level, opinionated API for creating Telegram bots efficiently. The library closely follows Telegram Bot API updates, releasing new versions frequently to incorporate the latest features and changes. The current stable version is 3.27.0.
pip install aiogram Common errors
error ImportError: cannot import name 'executor' from 'aiogram.utils' ↓
cause The 'executor' module was removed in aiogram version 3.x.
fix
Use 'await dp.start_polling(bot)' instead of 'executor.start_polling(dp)'.
error ImportError: cannot import name 'Dispatcher' from 'aiogram.dispatcher' ↓
cause In aiogram 3.x, 'Dispatcher' is imported directly from 'aiogram', not from 'aiogram.dispatcher'.
fix
Change the import statement to 'from aiogram import Dispatcher'.
error ImportError: cannot import name 'F' from 'aiogram' ↓
cause The 'F' object is not available in aiogram 2.x; it was introduced in version 3.x.
fix
Upgrade to aiogram 3.x to use 'F', or avoid using 'F' in aiogram 2.x.
error AttributeError: 'Dispatcher' object has no attribute 'callback_query_handler' ↓
cause In aiogram 3.x, 'callback_query_handler' is not a method of 'Dispatcher'; handlers are registered using routers.
fix
Use 'router.callback_query.register(your_handler)' to register callback query handlers.
error ImportError: cannot import name 'ContentTypes' from 'aiogram.filters' ↓
cause In aiogram 3.x, 'ContentTypes' is not available in 'aiogram.filters'.
fix
Use 'from aiogram.types import ContentType' instead.
Warnings
breaking aiogram v3 introduced significant breaking changes from v2. Key areas affected include handler registration, FSMContext usage, filters, and the main polling/webhook setup. ↓
fix Consult the official migration guide for aiogram v2 to v3. Update handler decorators (e.g., `@dp.message()` instead of `@dp.message_handler`), replace `executor.start_polling` with `dp.start_polling(bot)`, and adapt filter usage to the new `F` object.
gotcha aiogram is fully asynchronous. All I/O operations and handlers must be `async def` functions and use `await`. Mixing synchronous and asynchronous code incorrectly will lead to blocking, deadlocks, or unexpected behavior. ↓
fix Ensure all handlers and functions interacting with the Bot API are `async def`. Use `asyncio.to_thread` for calling blocking synchronous code if absolutely necessary within an async context.
gotcha Hardcoding your bot token directly in code is a security risk. It should be kept confidential and not exposed in version control. ↓
fix Always retrieve your bot token from environment variables (e.g., `os.environ.get('TELEGRAM_BOT_TOKEN')`) or a secure configuration management system. Never commit it directly to your codebase.
gotcha aiogram frequently updates to support new Telegram Bot API features. While this is beneficial, it means that minor API changes can sometimes introduce subtle breaking changes in types or available fields. ↓
fix Stay up-to-date with aiogram releases and review the changelog before upgrading to major or minor versions to understand any potential impacts on your bot's logic.
breaking aiogram v3.x has specific Python version requirements. As of v3.27.0, it requires Python `>=3.10` and `<3.15`. Python 3.9 is no longer supported as of v3.23.0. ↓
fix Ensure your project runs on a supported Python version (e.g., 3.10, 3.11, 3.12, 3.13, 3.14). Upgrade your Python environment if necessary. Check PyPI `requires_python` for the exact current range.
Install compatibility last tested: 2026-05-13 v3.22.0 installed · v3.28.2 latest
python os / libc status wheel install import disk mem side effects
3.10 alpine (musl) wheel - 5.91s 45.6M 42.0M clean
3.10 alpine (musl) - - 7.14s 45.5M 42.2M -
3.10 slim (glibc) wheel 7.5s 4.32s 47M 42.0M clean
3.10 slim (glibc) - - 5.71s 47M 42.2M -
3.11 alpine (musl) wheel - 7.02s 49.3M 41.2M clean
3.11 alpine (musl) - - 8.46s 49.3M 41.6M -
3.11 slim (glibc) wheel 5.9s 6.05s 51M 41.2M clean
3.11 slim (glibc) - - 7.08s 51M 41.5M -
3.12 alpine (musl) wheel - 5.47s 41.0M 41.3M clean
3.12 alpine (musl) - - 7.25s 40.9M 40.9M -
3.12 slim (glibc) wheel 4.5s 5.67s 42M 41.3M clean
3.12 slim (glibc) - - 7.39s 43M 40.9M -
3.13 alpine (musl) wheel - 5.43s 40.7M 41.6M clean
3.13 alpine (musl) - - 6.49s 40.5M 41.8M -
3.13 slim (glibc) wheel 4.9s 5.36s 42M 41.6M clean
3.13 slim (glibc) - - 6.83s 42M 41.8M -
3.9 alpine (musl) wheel - 5.26s 44.8M 38.1M clean
3.9 alpine (musl) - - 6.60s 44.8M 38.1M -
3.9 slim (glibc) wheel 8.6s 4.79s 47M 38.1M clean
3.9 slim (glibc) - - 6.91s 47M 38.1M -
Imports
- Bot
from aiogram import Bot - Dispatcher
from aiogram import Dispatcher - F wrong
from aiogram.dispatcher.filters import Textcorrectfrom aiogram import F - Message
from aiogram.types import Message - CommandStart
from aiogram.filters import CommandStart
Quickstart last tested: 2026-04-25
import asyncio
import os
from aiogram import Bot, Dispatcher, F
from aiogram.types import Message
from aiogram.filters import CommandStart
BOT_TOKEN = os.environ.get('TELEGRAM_BOT_TOKEN', 'YOUR_BOT_TOKEN_HERE') # Replace or set env var
async def main():
bot = Bot(token=BOT_TOKEN)
dp = Dispatcher()
@dp.message(CommandStart())
async def handle_start(message: Message):
await message.answer(f"Hello, {message.from_user.full_name}!")
@dp.message(F.text == "hi")
async def handle_hi(message: Message):
await message.answer("Hi there!")
@dp.message(F.text)
async def handle_text(message: Message):
await message.answer(f"You said: {message.text}")
await dp.start_polling(bot)
if __name__ == "__main__":
if BOT_TOKEN == 'YOUR_BOT_TOKEN_HERE':
print("Please replace 'YOUR_BOT_TOKEN_HERE' with your actual bot token or set the TELEGRAM_BOT_TOKEN environment variable.")
else:
asyncio.run(main())