Dependency Injector

Warnings

• breaking Python 3.7 support was dropped in version 4.47.0. Users on Python 3.7 or older must upgrade their Python version or stay on an older `dependency-injector` release.
  Fix: Upgrade Python to 3.8 or newer. For Python 3.7, use `dependency-injector<4.47.0`.
• gotcha Using `@inject` decorator without `Provide[...]` markers for parameters will produce a warning since version 4.48.1. This means the framework will not automatically infer which provider to use without the explicit marker.
  Fix: Ensure all parameters to `@inject`-decorated functions/methods that require injection use `param_name: Annotated[Type, Provide[Container.provider_name]]` or `param_name: Type = Provide[Container.provider_name]`.
• gotcha Pydantic v2 deprecation warnings could trigger in `dependency-injector` versions prior to 4.49.0 when using Pydantic for configuration. This was a compatibility issue.
  Fix: Upgrade to `dependency-injector` 4.49.0 or newer to resolve Pydantic v2 compatibility warnings.
• gotcha Incorrect monkeypatching during `container.wire()` in versions prior to 4.47.0 could violate Method Resolution Order (MRO) in some classes, leading to unexpected behavior.
  Fix: Upgrade to `dependency-injector` 4.47.0 or newer to ensure correct wiring and MRO preservation.
• gotcha A common anti-pattern in Dependency Injection is having longer-lived services (e.g., Singletons) depend on shorter-lived services (e.g., Factories, Resources intended per-request). This 'captive dependency' can lead to stale data, resource leaks, or unexpected behavior in concurrent applications.
  Fix: Carefully manage provider lifetimes. Avoid injecting 'Factory' or 'Resource' providers directly into 'Singleton' providers if their instance state should not be shared across the entire application lifecycle. Consider injecting a factory *callable* or creating a new scope explicitly if a fresh instance of the short-lived dependency is needed within the singleton.
• gotcha Performing blocking I/O or computationally heavy operations within Provider definitions or Module `configure` methods can introduce performance bottlenecks or deadlocks, as `dependency-injector` uses internal locks for thread safety during container initialization.
  Fix: Defer heavy operations and I/O to the actual service methods, not their construction or configuration. Providers should primarily focus on assembling dependencies quickly.

Install

• pip install dependency-injector Install stable version

Imports

• containers

  from dependency_injector import containers

• providers

  from dependency_injector import providers

• Provide

  from dependency_injector.wiring import Provide

  Use Provide[Container.service] for type hints to correctly mark dependencies for wiring.
• inject

  from dependency_injector.wiring import inject

  Since 4.48.1, @inject without explicit Provide[...] markers will raise a warning. Always use `service: Annotated[Service, Provide[Container.service]]` or similar.

Quickstart

This quickstart demonstrates defining a container with a Configuration provider, a Singleton service, and a Factory service. It shows how to inject dependencies into a function using `@inject` and `Provide` and how to configure values from environment variables.

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


class ConfigService:
    def __init__(self, api_key: str):
        self.api_key = api_key

    def get_api_key(self) -> str:
        return self.api_key


class MyService:
    def __init__(self, config_service: ConfigService):
        self.config_service = config_service

    def do_something(self) -> str:
        api_key = self.config_service.get_api_key()
        return f"Doing something with API Key: {api_key[:4]}..."


class Container(containers.DeclarativeContainer):
    config = providers.Configuration()
    config_service = providers.Singleton(
        ConfigService,
        api_key=config.api_key
    )
    my_service = providers.Factory(
        MyService,
        config_service=config_service
    )


@inject
def main_app_function(
    service: MyService = Provide[Container.my_service],
):
    print(service.do_something())


if __name__ == '__main__':
    container = Container()
    # Load configuration from environment variable (or .env file)
    container.config.api_key.from_env('MY_APP_API_KEY', as_=str, default='default_key_1234567890')

    # Example: Override during testing or development
    # container.config.api_key.override('test_key_abcde')

    container.wire(modules=[__name__])

    # Set an environment variable for the example to work
    os.environ['MY_APP_API_KEY'] = os.environ.get('MY_APP_API_KEY', 'example_api_key_12345')

    main_app_function()
    # Clean up environment variable (optional)
    del os.environ['MY_APP_API_KEY']