Install & Compatibility
Where this runs
tested against v2.7.7 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.244s · 18.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.7s · import 0.210s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Container
✓ from lagom import Container
injectable
✓ from lagom import injectable
Used with decorators like @bind_to_container to explicitly mark arguments for injection, especially when default values are present.
dependency_definition
✓ from lagom import dependency_definition
Decorator to explicitly register a function as a dependency constructor with the container, especially for async functions or complex build logic.
Awaitable
✓ from typing import Awaitable
✗ from lagom import Awaitable
Awaitable is part of Python's standard `typing` module, not Lagom. It's crucial for requesting async dependencies from the container.
This example demonstrates basic auto-wiring with `Container`, explicit dependency configuration, and integrating with functions using `@bind_to_container`. It shows how to provide a `Config` instance and how `HttpClient` and `MyService` are automatically resolved based on their type hints.
from lagom import Container, injectable
class Config:
def __init__(self, api_key: str):
self.api_key = api_key
class HttpClient:
def __init__(self, config: Config):
self.config = config
class MyService:
def __init__(self, http_client: HttpClient):
self.http_client = http_client
# Create a container
container = Container()
# Configure a dependency (e.g., from environment variables)
# In a real app, this might come from os.environ.get or a settings file
container[Config] = lambda: Config(api_key=os.environ.get('MY_API_KEY', 'default_api_key'))
# Lagom will auto-wire HttpClient and MyService based on type hints
service = container[MyService]
print(f"Service created with API Key: {service.http_client.config.api_key}")
# Example with function binding
from lagom.decorators import bind_to_container
@bind_to_container(container)
def process_request(service: MyService, request_data: dict):
print(f"Processing request with API Key: {service.http_client.config.api_key}")
return {"status": "ok", "data": request_data}
process_request(request_data={"id": 123})
Debug
Known issues
breakingLagom versions 2.0.0 dropped formal support for Python 3.6, and 2.7.0 dropped formal support for Python 3.8. Using these versions on unsupported Python runtimes may lead to unexpected behavior or compilation issues.fixUpgrade your Python environment to 3.9+ or use an older version of Lagom compatible with your Python version. Refer to Lagom's `requires_python` metadata for the latest compatibility.
affects: >=2.0.0 (Python 3.6), >=2.7.0 (Python 3.8)
gotchaAsynchronous dependencies defined with `async def` must be requested from the container as `Awaitable[YourType]` and then awaited. Attempting to directly resolve `YourType` will result in an error or an unawaited `Awaitable` object.fixIf your dependency `MyAsyncDep` is constructed by an `async def` function, retrieve it as `my_dep = await container[Awaitable[MyAsyncDep]]`. (Fixed a related `RuntimeError` for `Awaitable` singletons in 2.7.6).
affects: All versions with async support
gotchaWhen using Lagom's FastAPI integration, versions prior to 1.7.1 and between 2.4.2 and 2.7.5 had a bug where only the last defined request-level singleton would be correctly applied. This could lead to incorrect instances being injected for other request-scoped dependencies.fixUpgrade Lagom to version 2.7.5 or higher to ensure all request-level singletons are correctly registered and resolved within the FastAPI integration.
affects: <1.7.1, >2.4.2 & <2.7.5
Errors
Common errors & fixes
lagom.exceptions.TypeOnlyAvailableAsAwaitable: Unable to construct type <YourType> as it is only available as an async.Try requesting Awaitable[<YourType>] instead.
You are trying to resolve an asynchronous dependency directly as its concrete type (<YourType>) instead of wrapping it in `typing.Awaitable` and awaiting the result.
fixIf your dependency `MyAsyncDep` is defined by an `async def` constructor, you must request it as `my_dep = await container[Awaitable[MyAsyncDep]]`.
lagom.exceptions.UnresolvableType: Unable to construct dependency of type <YourType> The constructor probably has some unresolvable dependencies
Lagom could not determine how to construct `YourType` or one of its sub-dependencies. This can happen due to missing type hints, abstract types without concrete bindings, or unconfigured dependencies.
fixEnsure all constructor arguments have explicit type hints. If `YourType` is an abstract base class, provide a concrete implementation using `container[YourAbstractType] = YourConcreteClass`. For complex types, define a factory function: `container[YourType] = lambda c: YourType(c[DependencyA], c[DependencyB])`.
lagom.exceptions.RecursiveDefinitionError: When trying to build dependency of type '<YourType>' python hit a recursion limit. This could indicate a circular definition somewhere.
There is a circular dependency in your application's object graph (e.g., A depends on B, and B depends on A), causing infinite recursion during dependency resolution.
fixIdentify and break the circular dependency. This often involves introducing an interface, a factory function, or restructuring your classes to decouple their direct dependencies.
Upgrade
Version history
2.7.7latest on PyPI · released Jul 16, 2025
Audit
Dependencies
pydanticoptionalRequired for loading environment variables via `lagom.environment`.