{"id":2373,"library":"aiogram","title":"aiogram","description":"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.","status":"active","version":"3.27.0","language":"en","source_language":"en","source_url":"https://github.com/aiogram/aiogram/","tags":["telegram","bot","async","framework","asyncio"],"install":[{"cmd":"pip install aiogram","lang":"bash","label":"Install aiogram"}],"dependencies":[{"reason":"Used for data validation and parsing Telegram Bot API types.","package":"pydantic","optional":false}],"imports":[{"symbol":"Bot","correct":"from aiogram import Bot"},{"symbol":"Dispatcher","correct":"from aiogram import Dispatcher"},{"note":"F is a magic filter for elegant condition checking, replacing many old filter patterns.","wrong":"from aiogram.dispatcher.filters import Text","symbol":"F","correct":"from aiogram import F"},{"symbol":"Message","correct":"from aiogram.types import Message"},{"symbol":"CommandStart","correct":"from aiogram.filters import CommandStart"}],"quickstart":{"code":"import asyncio\nimport os\nfrom aiogram import Bot, Dispatcher, F\nfrom aiogram.types import Message\nfrom aiogram.filters import CommandStart\n\nBOT_TOKEN = os.environ.get('TELEGRAM_BOT_TOKEN', 'YOUR_BOT_TOKEN_HERE') # Replace or set env var\n\nasync def main():\n    bot = Bot(token=BOT_TOKEN)\n    dp = Dispatcher()\n\n    @dp.message(CommandStart())\n    async def handle_start(message: Message):\n        await message.answer(f\"Hello, {message.from_user.full_name}!\")\n\n    @dp.message(F.text == \"hi\")\n    async def handle_hi(message: Message):\n        await message.answer(\"Hi there!\")\n\n    @dp.message(F.text)\n    async def handle_text(message: Message):\n        await message.answer(f\"You said: {message.text}\")\n\n    await dp.start_polling(bot)\n\nif __name__ == \"__main__\":\n    if BOT_TOKEN == 'YOUR_BOT_TOKEN_HERE':\n        print(\"Please replace 'YOUR_BOT_TOKEN_HERE' with your actual bot token or set the TELEGRAM_BOT_TOKEN environment variable.\")\n    else:\n        asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"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.","message":"aiogram v3 introduced significant breaking changes from v2. Key areas affected include handler registration, FSMContext usage, filters, and the main polling/webhook setup.","severity":"breaking","affected_versions":"All versions migrating from aiogram v2 to v3+"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Hardcoding your bot token directly in code is a security risk. It should be kept confidential and not exposed in version control.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"aiogram v3.23.0 and newer"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}