DEV Community: Vlad Shulcz

How I made dependency injection in Python 130x faster: from reflection to compiling the graph

Vlad Shulcz — Thu, 18 Jun 2026 10:05:53 +0000

There's a stock argument against DI containers in Python: a container is just overhead, pass the dependency into the constructor yourself and stop overengineering. It sounds reasonable, and I believed it for a long time. But "sounds reasonable" isn't a number, so at some point I sat down and measured: what does a container actually cost on every resolve, and can you even catch up to hand-wiring without breaking the semantics?

Short version: you can get very close. But the number isn't really the point — the road there is, because most of the steps are tricks that pay off well beyond DI: spotting overhead that's invisible in a single call, deleting code that provably never runs, and keeping exec-based codegen from quietly breaking production along the way.

The setup

The graph is small but typical for a backend: singletons on top (config and a client), transient repository, email sender and audit below, and a RegisterUser use case that pulls all three. The benchmark resolves this graph in a loop; next to it, as a lower bound, the same objects built by hand. Same machine for every measurement. The numbers are synthetic and tied to the shape of the graph — this is not a universal ranking of containers, it's a reproducible check of one shape, and the script is open.

The starting point was sobering: by hand — 0.27 µs/op, the naive container — 52.9. Almost two hundred times slower. For reference, punq — a real reflection-based container — does about 57 µs/op on the same graph, so the number isn't made up. That's just what you get if you inspect constructors on every resolve.

Where 53 microseconds come from

The naive resolver reaches into the constructor on every call: it takes inspect.signature, calls get_type_hints, recursively resolves the dependencies from the annotations, and constructs the object. The problem is that get_type_hints and signature parsing are expensive — annotation evaluation, MRO walking, allocations. Once, it's nothing. A million times in a row, it's those tens of microseconds.

The obvious move: parse the graph once. At registration (or on the first resolve) you read the constructor and store a "plan" — which dependencies, in what order, with what lifetime. After that, resolving follows the plan, with no signature or get_type_hints at all.

That one change removes almost all of the cost: 52.9 → 0.818 µs/op, roughly 65×. And then comes the part people usually leave alone. They shouldn't.

Twist one: a check that could never fire

With the plan cached, every "fast" constructor was wrapped in a cycle guard:

def create(scope):
    if cls in resolving:                 # cycle guard
        raise CyclicDependencyException(cls)
    resolving.add(cls)
    try:
        return cls(dep0(scope), dep1(scope))
    finally:
        resolving.remove(cls)

A set lookup, an insert, a try/finally — per node, per resolve. Looks mandatory. But here's the catch: a fast constructor is only built when the subgraph is already proven acyclic. While building the plan, the moment it hits a cycle the compiler returns None, and that graph falls back to the slow, interpreted path — which is where the guard lives. So on the fast path, cls in resolving can never become true.

It's a guard that physically cannot fire. I removed it from the fast path; cycle detection stays where it actually works — in the interpreter and in a separate graph-validation step. A cyclic graph simply never gets a fast constructor and is caught as before. The takeaway: if an invariant is already guaranteed earlier in the code, re-checking it at runtime just costs you. A few percent, for free.

An allocation on every call

The profiler flagged one more small thing that's expensive because of how often it happens. resolve(SomeType) for the most common case — resolve by type, no name, no scope — built a key tuple (interface, None) and read a couple of registration attributes. Nanoseconds per call, but there are millions of calls. A direct type → constructor dict for that case (cleared when registrations change or a test override kicks in) gets rid of both the tuple allocation and the extra reads.

Twist two: compile the graph — and nearly break production

The biggest reserve was in the shape of the fast path itself. A transient graph was built as a tree of nested closures: resolving the use case called the use-case closure, which called the repository closure, which called the singleton client's getter. One function call per node. Worse, a shared singleton needed by two siblings was fetched twice.

The classic fix: glue the whole transient chain into one flat function — inline the constructors and compute each shared singleton once instead of twice. This is exactly what compilers call common-subexpression elimination (CSE).

Mechanically it's code generation: from the graph's plan I build the source of a function and bring it to life through exec inside a closure with the needed symbols. The leaves — singletons, scopes, instances — stay as the previous constructors (I don't touch their caching or lazy creation, I reuse them as-is); only the transient part becomes flat, which is exactly what runs on every resolve. Not a single class name or user value goes into the generated source — only opaque generated symbols, so there's nothing to inject through it.

That gave the main win: 0.818 → 0.401 µs/op. From the naive version, that's about 130×, and the container now trails hand-wiring by less than 1.5×.

And this is where I nearly stopped. exec-based code generation in a library is a special kind of risk. A bug in it doesn't fail with a stack trace. It quietly builds the wrong object in someone's production: hands you the wrong implementation, loses a shared singleton, swaps argument order. For DI, that's the worst case — "works, but wrong."

So I didn't ship it on vibes. I did the thing I'd recommend to anyone touching code generation: equivalence fuzzing. The idea is simple: generate thousands of random acyclic graphs with mixed lifetimes, optional and default parameters; resolve each one two ways — the compiled path and a separate, deliberately dumb reference resolver; and compare not the values, but the structure of the result. The same classes, and the same pattern of shared references — where a singleton must be the same object and a transient must be different ones.

4000 random graphs — the structure matched on every one

Whatever the compiler can't handle — factories, property injection, injecting the container itself, cycles — it honestly returns None and falls back to the old path. That harness, not "looks right," is the reason exec-generated code made it into a release at all. If you build something similar: a separate reference plus a structural comparison is worth more than a hundred hand-written tests.

Honest limits

So I don't oversell it. The numbers are synthetic and tied to the shape of the graph: with lots of scopes, async resources, or factories the picture is different — run it on yours. And if your wiring is mostly about async resource lifecycles or rich scopes — opening and closing pools or sessions as part of resolution — that's a different design with real merits, and libraries like dishka and dependency-injector are built for exactly that; this one isn't. The flat compilation speeds up exactly transient chains with shared singletons; if you're mostly factories or property injection, there's no win, because those nodes go down the interpreted path anyway. And below ~0.4 µs in pure Python without a C extension you can't meaningfully go: the next step is Cython, and that's a different conversation about dependencies.

Wrap-up

Version	Resolve, µs/op	What changed
by hand	0.271	lower bound
naive container	52.9	reflection on every resolve
+ cached plan	0.818	parse constructors once
+ flat function, CSE, dispatch dict	0.401	compiling the graph

Three things stuck with me from this one:

Measure first. "Containers are expensive" was intuition; the number (200× slower than hand-wiring) showed where the cost actually sat, and that 99% of it goes away with one plan cache.
Don't cling to code that provably never runs. Re-checking an invariant that's already guaranteed earlier is a cost with no upside.
exec-based codegen only behind an equivalence fuzzer. Silent wiring bugs are worse than crashes; a separate reference catches them in batches.

I did all of this on a small typed DI container I maintain — Injex, code and benchmark are open if you want the implementation details. But the techniques, not the library, are the point.

Fast dependency injection in Python without a provider framework

Vlad Shulcz — Tue, 09 Jun 2026 07:54:07 +0000

Python does not need a dependency injection container by default.
For small apps, direct constructor calls are clearer than any framework:

repo = UserRepository(settings.database_url)
email = EmailSender(settings.smtp_url)
use_case = RegisterUser(repo, email)

That is fine once.

The problem starts when the same object graph appears in more than one place:

FastAPI startup;
Typer commands;
background workers;
scripts;
tests.

At that point, the question is not "how do I inject everything?"

The better question is:

Where should application wiring live?

The boundary I want

For web apps, I like this split:

FastAPI owns HTTP adaptation;
Typer owns CLI adaptation;
workers own job adaptation;
the application owns service wiring.

That means repositories, gateways, and use cases should depend on normal Python types, not framework primitives.

A service should not need to know whether it was called from an HTTP request, a CLI command, a queue worker, or a test.

FastAPI Depends is not the whole composition root

FastAPI Depends is excellent at the request boundary.

It handles request data, authentication, headers, cookies, and per-request adapters.

But if the same service graph is used outside HTTP, the real composition root should live in plain Python.

A useful shape is:

def build_services(settings: Settings) -> Services:
    client = ApiClient(settings)
    repo = UserRepository(client)
    email = EmailSender(client)

    return Services(
        register_user=RegisterUser(repo, email),
    )

FastAPI can adapt that graph:

@asynccontextmanager
async def lifespan(app: FastAPI):
    app.state.services = build_services(load_settings())
    yield

def get_register_user(request: Request) -> RegisterUser:
    return request.app.state.services.register_user

Workers and CLIs can use the same builder directly:

services = build_services(load_settings())
services.register_user.execute("ada@example.com")

The rule of thumb:

FastAPI adapts HTTP. The application owns service wiring.

Start with factories

I still think plain factories are the best default.

If your graph is small, this is better than adding any container:

def build_register_user(settings: Settings) -> RegisterUser:
    client = ApiClient(settings)
    repo = UserRepository(client)
    email = EmailSender(client)

    return RegisterUser(repo, email)

A DI container becomes useful later, when the same graph starts repeating across entrypoints and tests.

Why I built Injex

I built Injex for that middle ground.

Not a full provider framework.
Not framework-specific dependency injection.
Not a replacement for FastAPI Depends.

The niche is small Python apps that want:

explicit registrations;
constructor injection from type hints;
singleton, transient, and scoped lifetimes;
test overrides;
graph validation before startup;
zero runtime dependencies.

Example:

from injex import Container


container = Container()

container.add_instance(Settings, settings)
container.add_singleton(ApiClient)
container.add_transient(UserRepository)
container.add_transient(EmailSender)
container.add_transient(RegisterUser)

container.assert_valid()

use_case = container.resolve(RegisterUser)

Application classes stay plain:

class RegisterUser:
    def __init__(self, repo: UserRepository, email: EmailSender):
        self.repo = repo
        self.email = email

No decorators required for constructor injection.
No provider DSL.
No runtime dependencies.

What changed in 1.3.0

Injex 1.3.0 focused on two things:

cleaner internals;
faster repeated resolves.

Internally, the package is now split into focused modules:

container.py;
planning.py;
registry.py;
errors.py.

For performance, Injex now caches dependency plans and uses a fast path for common constructor-injection graphs.

Benchmark

I added a reproducible benchmark for a small service graph:

singleton Settings;
singleton ApiClient(settings);
transient UserRepository(client);
transient EmailSender(client);
transient AuditLog(settings);
transient RegisterUser(repo, email, audit).

Local result

Library	Median resolve time
manual wiring	`0.265 µs/op`
Injex	`0.818 µs/op`
Wireup, same scope	`0.879 µs/op`
Wireup, scope per operation	`1.559 µs/op`
dependency-injector	`1.727 µs/op`
lagom	`9.794 µs/op`
punq	`56.795 µs/op`

This is not a universal ranking.

Different graphs, lifetimes, async resources, framework integrations, and request scope models can change results.

The benchmark exists to answer a narrower question:

Can explicit typed wiring stay small and fast?

For this graph, yes.

Reproduce it:

uv run --with punq --with lagom --with dependency-injector --with wireup \ python benchmarks/resolve_graph.py

When I would not use Injex

I would skip Injex when:

a few constructor calls are still clear;
a framework dependency system covers every entrypoint;
the app needs a large provider/configuration DSL;
the team does not want a container at all.

Manual wiring is still the baseline.

Where Injex fits

I would consider Injex when:

a service layer is reused by API, CLI, workers, and tests;
constructors already describe dependencies with type hints;
tests need temporary external-service overrides;
startup should catch missing registrations before first request/job;
the team wants explicit wiring without a large DI framework.

Links

Repo:
https://github.com/vshulcz/injex

Docs:
https://vshulcz.github.io/injex/

Performance notes:
https://vshulcz.github.io/injex/docs/performance.html

Compared to FastAPI Depends:
https://github.com/vshulcz/injex/blob/main/docs/fastapi-depends.md

When Python Manual Wiring Turns Into Copy-Paste Architecture

Vlad Shulcz — Tue, 26 May 2026 11:07:59 +0000

I usually avoid dependency injection containers in Python.

Not because dependency injection is bad. Most of us already do it when we pass objects into constructors. I avoid containers because small Python apps usually do not need one.

Manual wiring is often the right starting point:

repo = UserRepository()
email_sender = EmailSender()
register_user = RegisterUser(repo, email_sender)

That is explicit, easy to debug, and boring in a good way.

The problem starts when this code stops living in one place.

The Code Drifts

The same services need to be created across completely different entrypoints.

In api/routes.py:

register_user = RegisterUser(UserRepository(), EmailSender())

In cli/commands.py:

# Oops, forgot to update this one when dependencies changed?
register_user = RegisterUser(UserRepository(), MockEmailSender())

The code does not fail all at once. It drifts.

One entrypoint gets a new dependency:

register_user = RegisterUser(repo, email_sender, audit_log)

Another still creates the old version. A test uses a fake for one service but accidentally keeps a real client for another. A worker starts fine, then fails only when the first real job touches the missing path.

That is the kind of boring failure I wanted to avoid. It was not a big architecture disaster. It was worse in a boring way: tiny setup details repeated in enough places that forgetting one became easy.

The problem is not dependency injection

Most Python code already uses dependency injection in the boring sense:

class RegisterUser:
    def __init__(self, repo: UserRepository, email_sender: EmailSender):
        self.repo = repo
        self.email_sender = email_sender

The class is fine. It receives dependencies instead of creating them.

The mess appears around the class, when every entrypoint has to remember how to build the same graph.

Framework DI stops at the framework boundary

FastAPI Depends is useful. Framework dependency systems are good when the framework owns the entrypoint.

But application services often need to run elsewhere:

maintenance commands;
scheduled jobs;
message consumers;
tests;
local scripts.

I do not want my service layer to care whether it is being called from an API route, a CLI command, or a worker. Construction can stay at the edge. The service layer can stay plain.

I wanted something smaller than a full DI container

Python already has mature DI libraries. Some of them support provider objects, configuration systems, framework integrations, and dozens of advanced features.

That is useful if you need it. I wanted a smaller tool for the middle ground:

Normal constructor injection (no magic syntax).
Type hints as the wiring contract.
Singleton, transient, and scoped lifetimes.
Temporary overrides in tests.
Validation before startup.
Zero runtime dependencies & no decorators required on your services.

I built injex as one attempt at that middle ground.

Here is how the wiring can live in one place.

In a real app, these classes would live in separate modules. They are inline here to keep the example short:

# app/ioc.py
from abc import ABC, abstractmethod
from injex import Container

class UserRepository(ABC):
    @abstractmethod
    def save(self, email: str) -> int: ...

class SqlUserRepository(UserRepository):
    def save(self, email: str) -> int:
        return 42

class EmailSender:
    def send_welcome(self, email: str) -> None:
        print(f"Welcome, {email}")

class RegisterUser:
    def __init__(self, repo: UserRepository, email_sender: EmailSender):
        self.repo = repo
        self.email_sender = email_sender

    def execute(self, email: str) -> int:
        return self.repo.save(email)

# Centralized configuration
container = Container()

# Bind abstract interfaces to concrete implementations
container.add_singleton(UserRepository, SqlUserRepository)
container.add_singleton(EmailSender)
container.add_transient(RegisterUser)

container.assert_valid()

Now each entrypoint uses the same graph.

In your api/routes.py or cli/commands.py, you just resolve what you need:

from app.ioc import container, RegisterUser

use_case = container.resolve(RegisterUser)
use_case.execute("ada@example.com")

The service class stays plain Python. No decorators, no base class, no framework imports. The container only owns construction.

The part I care about most: validation

The most useful feature for me is not resolving objects. It is finding broken wiring before anything important runs.

If a dependency is missing, or a constructor annotation is wrong, I want to know at startup. Not after the first HTTP request. Not after the first worker job. Not in a rarely used CLI path at 3 AM.

container.assert_valid()

If you forgot to register AuditLog, startup fails immediately with a clear error:

Container validation failed with 1 error(s):
- RegisterUser: Dependency 'audit_log' is not registered: AuditLog.

Or you can collect errors explicitly in your CI/CD sanity-check script:

errors = container.validate()

if errors:
    for error in errors:
        print(error)
    raise SystemExit(1)

The crucial detail is that validation checks the dependency graph without constructing service instances. That matters when constructors open files, spin up thread pools, or establish heavy database connections.

Test overrides

Tests are where copy-pasted wiring becomes especially annoying.

You either rebuild the whole graph for each test, or you mutate shared setup and hope it gets restored correctly. I wanted replacement to be explicit and temporary:

class FakeEmailSender:
    def __init__(self):
        self.sent_to = []

    def send_welcome(self, email: str) -> None:
        self.sent_to.append(email)

fake_sender = FakeEmailSender()

# Explicit context manager for tests
with container.override(EmailSender, instance=fake_sender):
    use_case = container.resolve(RegisterUser)
    use_case.execute("test@example.com")

assert fake_sender.sent_to == ["test@example.com"]
# Outside the block, the original configuration is restored.

That keeps tests explicit without permanently mutating the production container or introducing side effects.

Scoped lifetimes

Some objects should live for one request, one job, or one message, but not for the whole lifecycle of the process.

class RequestContext:
    pass

container.add_scoped(RequestContext)

scope_a = container.create_scope()
scope_b = container.create_scope()

assert scope_a.resolve(RequestContext) is scope_a.resolve(RequestContext)
assert scope_a.resolve(RequestContext) is not scope_b.resolve(RequestContext)

This is ideal for message consumers (like Celery or RabbitMQ workers) that reuse long-lived clients but still need isolated per-job state.

Multiple implementations

Sometimes resolving one implementation is wrong. You want every handler, plugin, or pipeline step registered for the same interface.

container.add_singleton(Notifier, EmailNotifier)
container.add_singleton(Notifier, SlackNotifier)

# Resolve all registered implementations at once
for notifier in container.resolve_all(Notifier):
    notifier.notify("Deployment complete")

That is enough for simple fan-out notifications, plugin architectures, and processing pipelines.

When I would not use it

A container should pay rent. I would still skip one if:

the wiring fits in one file;
there is only one entrypoint;
tests can easily pass fakes directly via standard constructors;
the framework dependency system (like FastAPI) already covers 100% of your operational surface;
the project needs a massive provider/configuration ecosystem.

Manual wiring is still the baseline. A container should only appear when it removes repeated construction code instead of adding ceremony.

Closing

I am not trying to make Python look like Java. I still prefer manual wiring when an application is small enough.

I built injex for the awkward middle: the graph is repeated enough to hurt, but not complex enough to justify a large provider framework. It is small, type-hint driven, zero-dependency, and focused entirely on explicit app wiring.

If you have run into this problem in Python services, CLIs, workers, or tests, I would appreciate your feedback on the API and examples!

Links: