https://github.com/modern-python/modern-di

Powerful dependency-injection framework with IoC container and scopes
https://github.com/modern-python/modern-di

asyncio dependency-injection di ioc ioc-container mocks modern-di python scopes

Last synced: 12 days ago
JSON representation

Powerful dependency-injection framework with IoC container and scopes

• Host: GitHub
• URL: https://github.com/modern-python/modern-di
• Owner: modern-python
• License: mit
• Created: 2024-10-27T18:08:41.000Z (almost 2 years ago)
• Default Branch: main
• Last Pushed: 2026-07-28T10:21:04.000Z (12 days ago)
• Last Synced: 2026-07-28T12:06:12.516Z (12 days ago)
• Topics: asyncio, dependency-injection, di, ioc, ioc-container, mocks, modern-di, python, scopes
• Language: Python
• Homepage: https://modern-di.modern-python.org
• Size: 2.73 MB
• Stars: 60
• Watchers: 1
• Forks: 5
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE
  • Roadmap: ROADMAP.md

Awesome Lists containing this project

• awesome-dependency-injection-in-python - Modern DI - powerful DI-framework with scopes and IoC-container [🐍, MIT License]. (Software / DI Frameworks / Containers)
• awesome-fastapi - modern-di - Dependency injection framework with IoC container and scopes, with a [FastAPI integration](https://github.com/modern-python/modern-di-fastapi). (Third-Party Extensions / Dependency Injection)
• awesome-litestar - `modern-di` - Dependency injection framework with IoC container and scopes, including [Litestar integration](https://github.com/modern-python/modern-di-litestar). (Third-Party Extensions / General)

README

          


  

    

    

    

  



[![GitHub stars](https://img.shields.io/github/stars/modern-python/modern-di)](https://github.com/modern-python/modern-di/stargazers)

[![Context7](https://img.shields.io/badge/Context7-docs-blue)](https://context7.com/modern-python/modern-di)

[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)

[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)

| Project                                                                       | Badges                                                                                                                                                                                                                                                                 |

|-------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

| modern-di                                                                     | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di.svg)](https://pypi.python.org/pypi/modern-di) [![downloads](https://static.pepy.tech/badge/modern-di/month)](https://pepy.tech/projects/modern-di)                                             |

| [modern-di-aiogram](https://github.com/modern-python/modern-di-aiogram)       | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-aiogram.svg)](https://pypi.python.org/pypi/modern-di-aiogram) [![downloads](https://static.pepy.tech/badge/modern-di-aiogram/month)](https://pepy.tech/projects/modern-di-aiogram)             |

| [modern-di-aiohttp](https://github.com/modern-python/modern-di-aiohttp)       | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-aiohttp.svg)](https://pypi.python.org/pypi/modern-di-aiohttp) [![downloads](https://static.pepy.tech/badge/modern-di-aiohttp/month)](https://pepy.tech/projects/modern-di-aiohttp)             |

| [modern-di-arq](https://github.com/modern-python/modern-di-arq)               | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-arq.svg)](https://pypi.python.org/pypi/modern-di-arq) [![downloads](https://static.pepy.tech/badge/modern-di-arq/month)](https://pepy.tech/projects/modern-di-arq)                             |

| [modern-di-celery](https://github.com/modern-python/modern-di-celery)         | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-celery.svg)](https://pypi.python.org/pypi/modern-di-celery) [![downloads](https://static.pepy.tech/badge/modern-di-celery/month)](https://pepy.tech/projects/modern-di-celery)                 |

| [modern-di-fastapi](https://github.com/modern-python/modern-di-fastapi)       | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-fastapi.svg)](https://pypi.python.org/pypi/modern-di-fastapi) [![downloads](https://static.pepy.tech/badge/modern-di-fastapi/month)](https://pepy.tech/projects/modern-di-fastapi)             |

| [modern-di-faststream](https://github.com/modern-python/modern-di-faststream) | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-faststream.svg)](https://pypi.python.org/pypi/modern-di-faststream) [![downloads](https://static.pepy.tech/badge/modern-di-faststream/month)](https://pepy.tech/projects/modern-di-faststream) |

| [modern-di-flask](https://github.com/modern-python/modern-di-flask)           | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-flask.svg)](https://pypi.python.org/pypi/modern-di-flask) [![downloads](https://static.pepy.tech/badge/modern-di-flask/month)](https://pepy.tech/projects/modern-di-flask)                     |

| [modern-di-grpc](https://github.com/modern-python/modern-di-grpc)             | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-grpc.svg)](https://pypi.python.org/pypi/modern-di-grpc) [![downloads](https://static.pepy.tech/badge/modern-di-grpc/month)](https://pepy.tech/projects/modern-di-grpc)                         |

| [modern-di-litestar](https://github.com/modern-python/modern-di-litestar)     | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-litestar.svg)](https://pypi.python.org/pypi/modern-di-litestar) [![downloads](https://static.pepy.tech/badge/modern-di-litestar/month)](https://pepy.tech/projects/modern-di-litestar)         |

| [modern-di-pytest](https://github.com/modern-python/modern-di-pytest)         | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-pytest.svg)](https://pypi.python.org/pypi/modern-di-pytest) [![downloads](https://static.pepy.tech/badge/modern-di-pytest/month)](https://pepy.tech/projects/modern-di-pytest)                 |

| [modern-di-starlette](https://github.com/modern-python/modern-di-starlette)   | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-starlette.svg)](https://pypi.python.org/pypi/modern-di-starlette) [![downloads](https://static.pepy.tech/badge/modern-di-starlette/month)](https://pepy.tech/projects/modern-di-starlette)     |

| [modern-di-taskiq](https://github.com/modern-python/modern-di-taskiq)         | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-taskiq.svg)](https://pypi.python.org/pypi/modern-di-taskiq) [![downloads](https://static.pepy.tech/badge/modern-di-taskiq/month)](https://pepy.tech/projects/modern-di-taskiq)                 |

| [modern-di-typer](https://github.com/modern-python/modern-di-typer)           | [![Supported versions](https://img.shields.io/pypi/pyversions/modern-di-typer.svg)](https://pypi.python.org/pypi/modern-di-typer) [![downloads](https://static.pepy.tech/badge/modern-di-typer/month)](https://pepy.tech/projects/modern-di-typer)                     |

`modern-di` is a python dependency injection framework which supports the following:

- Automatic dependency graph based on type annotations

- Also, explicit dependencies are allowed where needed

- Scopes and context management

- Python 3.10+ support

- Fully typed and tested

- Integrations with `aiogram`, `aiohttp`, `arq`, `Celery`, `FastAPI`, `FastStream`, `Flask`, `gRPC`, `Litestar`, `Starlette`, `taskiq`, and `Typer`

- Pytest integration (`modern-di-pytest`) — turns any DI dependency into a pytest fixture

## Install

```bash

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

```

## Quick Start

```python

import dataclasses

from modern_di import Container, Group, Scope, providers

@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)

class Settings:

    database_url: str = "postgresql+asyncpg://localhost/app"

@dataclasses.dataclass(kw_only=True, slots=True)

class UserRepository:

    settings: Settings  # auto-injected by type

class Dependencies(Group):

    settings = providers.Factory(Settings, scope=Scope.APP)

    user_repository = providers.Factory(UserRepository, scope=Scope.REQUEST)

with Container(groups=[Dependencies]) as container:

    with container.build_child_container(scope=Scope.REQUEST) as request:

        repo = request.resolve(UserRepository)

        print(repo.settings.database_url)

```

See the [documentation](https://modern-di.modern-python.org) for scopes, lifecycles, finalizers, and framework integrations. `modern-di` is deliberately conservative — see [Design decisions](https://modern-di.modern-python.org/introduction/design-decisions/) for what it leaves out on purpose, including auto-binding, in-package integrations, and graph rendering.

Usage examples:

- with Litestar - [litestar-sqlalchemy-template](https://github.com/modern-python/litestar-sqlalchemy-template)

- with FastAPI - [fastapi-sqlalchemy-template](https://github.com/modern-python/fastapi-sqlalchemy-template)

## 📚 [Documentation](https://modern-di.modern-python.org)

## 📦 [PyPI](https://pypi.org/project/modern-di)

## 📝 [License](LICENSE)

## Part of `modern-python`

Browse the full list of templates and libraries in

[`modern-python`](https://github.com/modern-python) — see the org profile for the categorized index.