Install & Compatibility
Where this runs
tested against v3.31.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 10.910s · 46.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.4s · import 10.304s · 48MB
46MB installed
● package 46MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Bot
✓ from aiogram import Bot
Dispatcher
✓ from aiogram import Dispatcher
F
✓ from aiogram import F
✗ from aiogram.dispatcher.filters import Text
F is a magic filter for elegant condition checking, replacing many old filter patterns.
Message
✓ from aiogram.types import Message
CommandStart
✓ from aiogram.filters import CommandStart
This quickstart demonstrates a basic 'echo' bot using `aiogram v3`. It initializes a `Bot` and `Dispatcher`, defines handlers for the `/start` command and any text message, and then starts polling for updates. Remember to replace 'YOUR_BOT_TOKEN_HERE' or set the `TELEGRAM_BOT_TOKEN` environment variable.
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())
Debug
Known issues
breakingaiogram v3 introduced significant breaking changes from v2. Key areas affected include handler registration, FSMContext usage, filters, and the main polling/webhook setup.fixConsult 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.
affects: All versions migrating from aiogram v2 to v3+
gotchaaiogram 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.fixEnsure 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.
affects: All versions
gotchaHardcoding your bot token directly in code is a security risk. It should be kept confidential and not exposed in version control.fixAlways 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. affects: All versions
gotchaaiogram 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.fixStay 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.
affects: All versions
breakingaiogram 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.fixEnsure 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.
affects: aiogram v3.23.0 and newer
Errors
Common errors & fixes
ImportError: cannot import name 'executor' from 'aiogram.utils'
The 'executor' module was removed in aiogram version 3.x.
fixUse 'await dp.start_polling(bot)' instead of 'executor.start_polling(dp)'.
ImportError: cannot import name 'Dispatcher' from 'aiogram.dispatcher'
In aiogram 3.x, 'Dispatcher' is imported directly from 'aiogram', not from 'aiogram.dispatcher'.
fixChange the import statement to 'from aiogram import Dispatcher'.
ImportError: cannot import name 'F' from 'aiogram'
The 'F' object is not available in aiogram 2.x; it was introduced in version 3.x.
fixUpgrade to aiogram 3.x to use 'F', or avoid using 'F' in aiogram 2.x.
AttributeError: 'Dispatcher' object has no attribute 'callback_query_handler'
In aiogram 3.x, 'callback_query_handler' is not a method of 'Dispatcher'; handlers are registered using routers.
fixUse 'router.callback_query.register(your_handler)' to register callback query handlers.
ImportError: cannot import name 'ContentTypes' from 'aiogram.filters'
In aiogram 3.x, 'ContentTypes' is not available in 'aiogram.filters'.
fixUse 'from aiogram.types import ContentType' instead.
Upgrade
Version history
3.31.0latest on PyPI · released Aug 26, 2026
Audit
Dependencies
pydanticrequiredUsed for data validation and parsing Telegram Bot API types.