[Python] python dependency_injector, injector 라이브러리

1. 개요

Python에서 의존성 주입(Dependency Injection, DI)을 구현하기 위한 라이브러리는 다양합니다. 그 중 가장 널리 사용되는 두 라이브러리인 dependency-injector와 injector를 비교하고 정리합니다.

의존성 주입(DI)이란, 객체가 필요로 하는 다른 객체(의존성)를 직접 생성하지 않고 외부에서 전달받는 설계 패턴입니다. DI를 사용하면 코드의 결합도를 낮추고, 테스트를 용이하게 하며, 유지보수성을 높일 수 있습니다.

항목	dependency-injector	injector
PyPI 패키지명	dependency-injector	injector
GitHub Stars	4,800+	1,500+
최신 버전	4.49.0 (2026.03)	0.24.0 (2026.01)
Python 지원	3.8 ~ 3.14	3.10+ (CPython, PyPy)
설계 철학	명시적 컨테이너 기반	Google Guice 스타일 (타입 어노테이션 기반)
구현 언어	Python + Cython	순수 Python
라이선스	BSD-3-Clause	BSD-3-Clause

---

2. 각 라이브러리에 대한 설명

dependency-injector

dependency-injector는 명시적인 것이 암묵적인 것보다 낫다(Explicit is better than implicit)는 Python의 Zen 철학을 따르는 DI 프레임워크입니다. 모든 의존성 조립(assembly) 규칙을 하나의 Container에 선언적으로 정의하는 방식을 사용합니다.

핵심 컴포넌트

Container

애플리케이션의 모든 의존성 조립 규칙을 선언하는 클래스입니다.

• DeclarativeContainer — 클래스 기반으로 명시적으로 구조를 정의하는 방식 (가장 일반적)
• DynamicContainer — 런타임에 동적으로 컨테이너를 구성하는 방식

Provider (의존성 제공 방식)

Provider	역할
Factory	호출할 때마다 새 인스턴스 생성
Singleton	최초 한 번만 생성, 이후 동일 인스턴스 반환
Callable	일반 함수/callable 래핑
Coroutine	async 코루틴 래핑
Object	이미 생성된 객체를 그대로 제공
Configuration	YAML, JSON, INI, 환경변수에서 설정 로드
Resource	초기화/정리가 필요한 리소스 생명주기 관리
Selector	조건에 따라 다른 Provider를 선택

Wiring (와이어링)

컨테이너를 직접 참조하지 않고도 @inject 데코레이터와 Provide[...] 마커를 사용해 함수나 메서드에 자동으로 의존성을 주입하는 기능입니다.

---

injector

injector는 Google의 Java DI 프레임워크인 Guice에서 영감을 받아 Pythonic하게 재해석된 DI 프레임워크입니다. Python의 타입 어노테이션(__annotations__)을 런타임에 읽어 의존성을 자동으로 해결합니다.

핵심 컴포넌트

Injector

의존성 그래프를 관리하는 중앙 컨테이너입니다. 모듈 목록을 받아 초기화하고 .get(Type) 메서드로 인스턴스를 요청합니다.

@inject 데코레이터

생성자 또는 함수에 붙여 해당 파라미터의 타입 어노테이션을 기반으로 의존성을 자동 주입하도록 표시합니다.

Module 클래스

바인딩(타입 → 구현체)을 선언하는 설정 단위입니다. configure(binder) 메서드를 오버라이드하거나 @provider 메서드를 정의합니다.

@provider 데코레이터

Module 내에서 복잡한 객체 생성 로직을 팩토리 메서드로 선언할 때 사용합니다. 반환 타입 어노테이션이 바인딩 키가 됩니다.

@singleton 데코레이터

클래스나 @provider 메서드에 적용하여 해당 타입을 싱글턴 스코프로 선언합니다.

설계 원칙

• 단순성: 멤버 주입, 메서드 주입 같은 복잡한 기능은 의도적으로 제외
• 전역 상태 없음: 여러 독립적인 Injector 인스턴스 공존 가능
• 정적 타입 호환: mypy 등과 완전히 호환되는 API 설계
• 최소 침투: @inject 마커만 있으면 프레임워크 없이도 동작 가능

---

3. 각 라이브러리에 대한 사용 예시

dependency-injector 사용 예시

기본 사용법

from dependency_injector import containers, providers
from dependency_injector.wiring import Provide, inject

class ApiClient:
    def __init__(self, api_key: str, timeout: int):
        self.api_key = api_key
        self.timeout = timeout

class Service:
    def __init__(self, api_client: ApiClient):
        self.api_client = api_client

class Container(containers.DeclarativeContainer):
    config = providers.Configuration()

    # Singleton: 앱 전체에서 하나의 ApiClient 인스턴스 공유
    api_client = providers.Singleton(
        ApiClient,
        api_key=config.api_key,
        timeout=config.timeout,
    )

    # Factory: 호출마다 새 Service 인스턴스 생성
    service = providers.Factory(
        Service,
        api_client=api_client,
    )

@inject
def main(service: Service = Provide[Container.service]) -> None:
    print(f"API key: {service.api_client.api_key}")

if __name__ == "__main__":
    container = Container()
    container.config.api_key.from_env("API_KEY", required=True)
    container.config.timeout.from_env("TIMEOUT", as_=int, default=5)
    container.wire(modules=[__name__])
    main()  # 의존성이 자동으로 주입됩니다

FastAPI 통합 예시

# containers.py
from dependency_injector import containers, providers
from .database import Database
from .repositories import UserRepository
from .services import UserService

class Container(containers.DeclarativeContainer):
    wiring_config = containers.WiringConfiguration(modules=[".endpoints"])
    config = providers.Configuration(yaml_files=["config.yml"])
    db = providers.Singleton(Database, db_url=config.db.url)
    user_repository = providers.Factory(
        UserRepository,
        session_factory=db.provided.session,
    )
    user_service = providers.Factory(
        UserService,
        user_repository=user_repository,
    )

# endpoints.py
from typing import Annotated
from fastapi import APIRouter, Depends
from dependency_injector.wiring import Provide, inject
from .containers import Container
from .services import UserService

router = APIRouter()

@router.get("/users")
@inject
def get_list(
    user_service: Annotated[UserService, Depends(Provide[Container.user_service])],
):
    return user_service.get_users()

테스트 시 Mock 교체 (override)

from unittest import mock

with container.api_client.override(mock.Mock()):
    main()  # Mock이 자동 주입됩니다

---

injector 사용 예시

기본 사용법

from injector import Injector, inject

class Inner:
    def __init__(self):
        self.value = 42

class Outer:
    @inject
    def __init__(self, inner: Inner):
        self.inner = inner

injector = Injector()
outer = injector.get(Outer)
print(outer.inner.value)  # 42

Module 정의와 바인딩

import sqlite3
from injector import Injector, Module, provider, singleton, inject

class Configuration:
    def __init__(self, connection_string: str):
        self.connection_string = connection_string

class DatabaseModule(Module):
    @singleton
    @provider
    def provide_connection(self, config: Configuration) -> sqlite3.Connection:
        return sqlite3.connect(config.connection_string)

def configure_for_testing(binder):
    binder.bind(Configuration, to=Configuration(":memory:"), scope=singleton)

injector = Injector([configure_for_testing, DatabaseModule])
conn = injector.get(sqlite3.Connection)

인터페이스 추상화 패턴

from abc import ABC, abstractmethod
from injector import Injector, Module, inject

class NotificationService(ABC):
    @abstractmethod
    def send(self, message: str) -> None: ...

class EmailService(NotificationService):
    def send(self, message: str) -> None:
        print(f"Email: {message}")

class ProductionModule(Module):
    def configure(self, binder):
        binder.bind(NotificationService, to=EmailService)

class AlertService:
    @inject
    def __init__(self, notifier: NotificationService):
        self.notifier = notifier

injector = Injector([ProductionModule])
injector.get(AlertService).notifier.send("알림")  # Email: 알림

dataclass와 함께 사용

from dataclasses import dataclass
from injector import Injector, inject

class Database:
    url = "sqlite:///:memory:"

@inject
@dataclass
class Repository:
    db: Database

injector = Injector()
repo = injector.get(Repository)
print(repo.db.url)

---

4. 각 라이브러리에 대해 언제 쓰고 쓰면 왜 좋은지

dependency-injector를 사용하면 좋은 경우

적합한 상황

• 대규모 애플리케이션: 수십 개 이상의 서비스/컴포넌트가 복잡하게 얽혀 있는 프로젝트에서 의존성 조립 코드를 Container 하나로 집중시킬 수 있습니다.
• 환경별 설정이 많은 서비스: dev/stage/prod 환경에 따라 Selector Provider를 사용해 다른 구현체를 쉽게 전환할 수 있습니다.
• 설정 관리가 복잡한 프로젝트: YAML, JSON, INI, Pydantic Settings, 환경변수를 Configuration Provider 하나로 통합 관리할 수 있습니다.
• FastAPI, Flask, Django, Aiohttp 기반 웹 서비스: 공식 통합 예제가 풍부하게 제공됩니다.
• 비동기(async) 애플리케이션: Coroutine Provider와 async wiring이 기본 지원됩니다.

주요 장점

장점	설명
명시성	모든 의존성이 Container에 선언되어 있어 코드 가독성이 높습니다
테스트 친화성	override() API로 Mock 교체가 직관적입니다
성능	Cython으로 구현되어 순수 Python 대비 빠릅니다
타입 안전성	mypy와 완전히 호환되는 타입 스텁을 제공합니다
풍부한 문서	900개 이상의 공식 코드 스니펫과 프레임워크 통합 예제가 있습니다
설정 통합	다양한 설정 소스를 하나의 Provider로 처리합니다

---

injector를 사용하면 좋은 경우

적합한 상황

• 인터페이스-구현 분리가 중요한 프로젝트: 추상 클래스에 바인딩하여 구현체를 쉽게 교체할 수 있습니다.
• 환경별 Module 교체가 필요한 경우: 프로덕션/테스트 모듈을 교체하는 것만으로 전체 동작을 변경할 수 있습니다.
• 보일러플레이트를 최소화하고 싶을 때: 타입 어노테이션만으로 의존성이 자동 전이 해결(transitive resolution)됩니다.
• 전역 상태를 피하고 싶은 프로젝트: Injector 인스턴스 단위로 싱글턴 라이프사이클을 관리합니다.
• Guice 스타일 DI에 익숙한 개발자: Java의 Guice 패턴을 Python에서 그대로 적용할 수 있습니다.

주요 장점

장점	설명
자동 전이 해결	A → B → C 관계를 수동으로 연결할 필요 없습니다
전역 상태 없음	테스트마다 새 Injector 인스턴스로 완전 격리가 가능합니다
mypy 완전 호환	injector.get(SomeType)이 SomeType을 반환한다고 정적 추론합니다
프레임워크 독립	@inject 마커만 있으면 프레임워크 없이도 일반 객체로 사용 가능합니다
dataclass 지원	@inject @dataclass 조합으로 보일러플레이트를 최소화합니다

---

5. 두 라이브러리의 차이점

핵심 철학의 차이

관점	dependency-injector	injector
의존성 정의 방식	Container에 모든 Provider를 명시적으로 선언	타입 어노테이션 기반 자동 해결
설계 영감	Python Zen ("명시 > 암묵")	Google Guice (타입 안전 DI)
전역 상태	Container 인스턴스가 전역적으로 사용됨	Injector 인스턴스 단위 (전역 상태 없음)
자동 바인딩	없음 (모든 것을 명시적으로 등록)	있음 (타입 어노테이션으로 자동 해결)

상세 비교

기준	dependency-injector	injector
학습 곡선	높음 (Container, Provider, Wiring 등 많은 개념)	중간 (Module, Binder, @inject)
보일러플레이트	많음 (모든 의존성을 Provider로 선언 필요)	적음 (타입 어노테이션이 키)
성능	빠름 (Cython 구현)	보통 (순수 Python)
문서 품질	풍부 (900개+ 스니펫, 다양한 프레임워크 예제)	보통 (44개 스니펫)
FastAPI 통합	내장 지원 (공식 예제 다수)	별도 패키지 필요 (fastapi-injector)
테스트 Mock 교체	override() API — 매우 직관적	테스트용 Module 정의 후 Injector 재생성
설정 관리	Configuration Provider로 통합 관리	직접 Module에서 처리
비동기 지원	기본 내장 (Coroutine Provider, async wiring)	기본 비동기 미지원
스레드 안전성	비교적 안전	내부 잠금(Lock)으로 단일 스레드 DI 작업 제약
Python 버전	3.8 ~ 3.14	3.10+
GitHub Stars	4,800+	1,500+
커뮤니티/생태계	더 활발	상대적으로 작음

코드 스타일 비교

같은 기능을 두 라이브러리로 구현한 예시입니다.

dependency-injector 방식:

class Container(containers.DeclarativeContainer):
    config = providers.Configuration()
    db = providers.Singleton(Database, url=config.db.url)
    repo = providers.Factory(UserRepository, db=db)
    service = providers.Factory(UserService, repo=repo)

container = Container()
container.wire(modules=[__name__])

@inject
def handle(service: UserService = Provide[Container.service]):
    ...

injector 방식:

class AppModule(Module):
    @singleton
    @provider
    def provide_db(self, config: Config) -> Database:
        return Database(config.db_url)

class UserService:
    @inject
    def __init__(self, repo: UserRepository):
        self.repo = repo

injector = Injector([AppModule])
service = injector.get(UserService)

---

6. 결론

선택 기준 요약

상황	추천 라이브러리
대규모 엔터프라이즈 애플리케이션	dependency-injector
의존성 그래프가 복잡하고 명시적 관리가 필요	dependency-injector
FastAPI 공식 통합이 필요	dependency-injector
환경변수/YAML 설정 통합 관리	dependency-injector
보일러플레이트를 최소화하고 싶음	injector
Java Guice 스타일 DI 선호	injector
전역 상태 없이 격리된 테스트 환경 구성	injector
인터페이스-구현 분리 패턴 중심 설계	injector

최종 권장 사항

dependency-injector는 명시적이고 중앙 집중적인 의존성 관리를 원하는 프로젝트에 적합합니다. 모든 의존성이 Container에 선언되어 있어 코드베이스의 전체 구조를 한눈에 파악할 수 있으며, FastAPI를 포함한 다양한 프레임워크와의 통합 예제가 풍부합니다. 단, 모든 의존성을 명시적으로 등록해야 한다는 점에서 보일러플레이트가 증가할 수 있습니다.

injector는 타입 어노테이션 기반의 자동 의존성 해결을 원하는 프로젝트에 적합합니다. Google Guice 스타일의 Module 시스템과 전역 상태 없는 설계 덕분에 테스트 격리가 뛰어나며, @inject 마커만으로 의존성을 자동으로 전이 해결할 수 있습니다. 단, FastAPI 통합에는 별도 패키지가 필요하고 비동기 지원이 제한적입니다.

두 라이브러리 모두 프로덕션 환경에서 충분히 검증된 도구이므로, 팀의 경험과 프로젝트의 규모, 그리고 선호하는 코딩 스타일에 따라 선택하시면 됩니다.

---

7. pydantic-settings와의 비교

핵심 전제: 이 세 라이브러리는 레이어가 다르다

pydantic-settings는 dependency-injector, injector와 경쟁 관계가 아닙니다. 각자 다른 문제를 풀기 때문에 함께 사용하는 것이 이상적입니다.

라이브러리	카테고리	핵심 질문
dependency-injector	DI 컨테이너 프레임워크	"객체를 어떻게 조립하고 주입할 것인가?"
injector	DI 프레임워크 (경량)	"타입 힌트 기반으로 자동으로 의존성을 해소할 수 있는가?"
pydantic-settings	설정/환경변수 관리	"환경변수·dotenv를 타입 안전하게 읽어올 수 있는가?"

---

pydantic-settings란

pydantic-settings는 설정값·환경변수 관리 전용 라이브러리입니다. BaseSettings를 상속한 클래스를 정의하면 환경변수, dotenv, JSON, 파일 시크릿 등 여러 소스에서 값을 자동으로 읽어 타입 검증 후 파이썬 객체로 제공합니다.

핵심 개념

• BaseSettings — BaseModel의 설정 전용 서브클래스. 환경변수 자동 로드
• SettingsConfigDict — env_prefix, env_file, env_nested_delimiter 등 소스 설정
• 우선순위 (높음→낮음): 코드 내 명시적 값 > 환경변수 > dotenv 파일 > 기본값
• Secrets 지원: 파일 기반 시크릿 (Docker secrets 패턴) 직접 지원

기본 사용 예시

from pydantic import Field
from pydantic_settings import BaseSettings, SettingsConfigDict
from functools import lru_cache
from fastapi import Depends

class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_prefix='APP_',        # APP_DATABASE_HOST 형태로 읽음
        env_file='.env',
        env_file_encoding='utf-8',
        extra='ignore',
    )

    database_host: str = 'localhost'
    database_port: int = 5432     # str → int 자동 변환 및 검증
    api_key: str = Field(validation_alias='AUTH_API_KEY')
    debug: bool = False

@lru_cache  # 환경변수를 한 번만 읽어 캐시
def get_settings() -> Settings:
    return Settings()

# FastAPI에서 관용적 사용 패턴
async def some_endpoint(settings: Settings = Depends(get_settings)):
    return {"host": settings.database_host}

---

개념적 차이: 무엇이 다른가

pydantic-settings           dependency-injector / injector
───────────────────────────────────────────────────────────────
"어디서 값을 읽는가?"    vs   "누가 무엇을 만드는가?"

환경변수 → 파싱 → 검증        객체A → 객체B를 필요로 함
    → Settings 객체 반환           → Container가 조립해서 주입

관심사: 설정값의 소스와 타입     관심사: 객체 생성·수명·의존관계

기준	pydantic-settings	dependency-injector	injector
역할	설정값 로드·검증	객체 그래프 조립	객체 그래프 조립
DI 기능	없음	있음 (핵심 기능)	있음 (핵심 기능)
환경변수 파싱	있음 (핵심 기능)	부분 지원 (Configuration Provider)	없음 (직접 처리)
타입 검증	Pydantic 기반 강력한 검증	없음	없음
테스트 Mock 교체	lru_cache 무효화 필요, 번거로움	override() API로 직관적	테스트용 Module 재정의
객체 수명 관리	없음	Singleton / Factory Provider	@singleton 데코레이터
FastAPI 통합	Depends(get_settings) 패턴	Depends(Provide[Container.xxx])	fastapi-injector 별도 패키지

pydantic-settings가 할 수 없는 것

• 서비스 객체 간의 의존성 그래프를 관리하지 않음
• 객체 수명(Singleton/Factory) 제어 불가
• 런타임 Mock 교체가 어려움 (@lru_cache 무효화 패턴 필요)

dependency-injector의 Configuration Provider와의 차이

dependency-injector는 자체적인 Configuration Provider를 통해 환경변수·YAML·INI를 읽을 수 있지만, pydantic-settings에 비해 타입 검증이 약합니다.

기준	Configuration Provider	pydantic-settings
타입 변환	.as_int(), .as_float() 수동 호출	선언만 하면 자동 변환 및 검증
유효성 검사	없음	Pydantic validator 완전 지원
중첩 설정	config.db.host 형태	중첩 모델로 선언적 처리
dotenv 지원	외부에서 로드 후 from_dict	기본 내장
Docker secrets	직접 구현 필요	기본 지원

---

함께 사용하는 조합 패턴 (권장)

세 라이브러리는 레이어를 나눠서 함께 사용할 수 있으며, 대규모 FastAPI 앱에서 가장 견고한 구성입니다.

pydantic-settings       →  설정값·환경변수 로드·검증 담당
       ↓
dependency-injector     →  설정값을 Configuration Provider로 주입받아
                           서비스 객체 그래프 조립 담당

dependency-injector는 providers.Configuration(pydantic_settings=[...]) 로 pydantic-settings 인스턴스를 공식 지원합니다.

from pydantic_settings import BaseSettings
from dependency_injector import containers, providers

class AppSettings(BaseSettings):
    redis_host: str = "localhost"
    redis_port: int = 6379
    api_key: str

class Container(containers.DeclarativeContainer):
    # pydantic-settings가 환경변수 로드·검증 담당
    # dependency-injector가 객체 조립 담당
    config = providers.Configuration(pydantic_settings=[AppSettings()])

    redis_client = providers.Singleton(
        RedisClient,
        host=config.redis_host,
        port=config.redis_port.as_int(),
    )
    api_client = providers.Factory(
        ApiClient,
        api_key=config.api_key,
    )

---

언제 무엇을 선택하는가

상황	선택
환경변수·dotenv를 타입 안전하게 읽고 싶다	pydantic-settings
FastAPI 소규모 프로젝트에서 설정만 필요하다	pydantic-settings • Depends(get_settings)
중·대규모 앱에서 객체 그래프 전체를 명시적으로 관리하고 싶다	dependency-injector
설정 검증 + 객체 조립을 모두 견고하게 하고 싶다	pydantic-settings • dependency-injector 조합
Guice 스타일이 익숙하고 가벼운 DI가 필요하다	injector
테스트 시 서비스 목을 컨테이너 레벨에서 교체해야 한다	dependency-injector (override() 패턴)