Modern-DI integration for aiogram 3.x.

Full guide: aiogram integration docs

Installation

uv add modern-di-aiogram      # or: pip install modern-di-aiogram

Usage

aiogram has no dependency-injection system of its own, so modern-di-aiogram pairs an @inject decorator with inert FromDI markers (or auto_inject=True to skip the decorator entirely). setup_di opens the root container on dispatcher startup, closes it on shutdown, and installs an outer middleware that builds a per-update Scope.REQUEST child container automatically.

import typing

from aiogram import Dispatcher
from aiogram.types import Message
from modern_di import Container, Group, Scope, providers
from modern_di_aiogram import FromDI, inject, setup_di


class Settings:
    def __init__(self) -> None:
        self.greeting = "hello"


class AppGroup(Group):
    settings = providers.Factory(Settings, scope=Scope.APP, cache=True)


dispatcher = Dispatcher()
setup_di(dispatcher, Container(groups=[AppGroup], validate=True))


@dispatcher.message()
@inject
async def greet(
    message: Message,
    settings: typing.Annotated[Settings, FromDI(AppGroup.settings)],
) -> None:
    await message.answer(f"{settings.greeting}, {message.from_user.first_name}")

Pass auto_inject=True to setup_di to wrap every handler already registered on the dispatcher, so individual handlers don't need @inject — register handlers before startup for this to take effect. The current aiogram.types.Update and the concrete event it carries (Message, CallbackQuery, …) are resolvable within DI via the pre-built aiogram_update_provider / aiogram_event_provider context providers. aiogram-dialog getters and callbacks are supported via modern_di_aiogram.dialog — see the docs.

API

Symbol	Description
setup_di(dispatcher, container, *, auto_inject=False)	Stores the container on the dispatcher, registers the update/event providers, wires dispatcher.startup/dispatcher.shutdown to open/close it, and installs the per-update middleware. With auto_inject=True, also wraps every handler already registered at startup
FromDI(dependency)	Inert marker (used with @inject) that resolves a provider or type from the per-update child container
inject(handler)	Decorator for an aiogram handler; resolves its FromDI-annotated parameters. Not needed when setup_di(..., auto_inject=True) is used
fetch_di_container(dispatcher)	Returns the root Container stored on the dispatcher
aiogram_update_provider	ContextProvider for the current aiogram.types.Update (REQUEST scope)
aiogram_event_provider	ContextProvider for the current aiogram.types.TelegramObject (REQUEST scope) — the concrete event unwrapped from the Update

📦 PyPI

📝 License

Part of modern-python

Built on modern-di, a dependency-injection framework with IoC container and scopes.

Browse the full list of templates and libraries in modern-python — see the org profile for the categorized index.