Chat on WhatsApp
Toggle Nav
My Cart
Magento glossary

What is Magento DI Compile ?

Magento DI Compile (bin/magento setup:di:compile) is Magento's dependency-injection compilation step. The framework's runtime DI system needs auto-generated files — proxies, interceptors, factories, and repository classes — for every module's di.xml. In developer mode these files generate on demand; in production mode they must be pre-generated. Output goes to generated/code/ and generated/metadata/.

Need help with DI errors? How it works

Written by Kishan Savaliya — Adobe Certified Magento & Hyvä developer, 8 years on platform

How it works

Five things di:compile actually does under the hood

The compile step is not a black box. Here is exactly what happens between the moment you hit Enter and the moment generated/code/ is repopulated.

  1. 01

    Scans every di.xml across the codebase

    The compiler walks app/code, vendor/, and every active theme directory, picking up every etc/di.xml and etc/<area>/di.xml it can find. It builds an in-memory map of every preference, type, plugin, and virtualType declaration. That map becomes the source of truth for which classes need code generation and in what order plugins should run.

  2. 02

    Auto-generates Proxy, Factory, and Interceptor classes

    For every class referenced as a \Proxy target the compiler emits a lazy-loading wrapper that defers construction until first method call. For non-injectable objects (value objects, search criteria) it emits a \Factory. For any class with at least one plugin it emits a \Interceptor subclass — that is the class Magento actually instantiates at runtime, never the original. Repository classes referenced by @api service contracts also get generated wrappers.

  3. 03

    Resolves plugin lists per class at compile time

    Magento's plugin system supports before, around, and after hooks declared by sortOrder. At runtime, resolving this list on every method call would be expensive — so the compiler stitches the full plugin chain into the Interceptor source code ahead of time. After compile, every plugin invocation is a static method dispatch, not a reflection lookup. That is most of the performance gap between developer and production mode.

  4. 04

    Writes everything under generated/code and generated/metadata

    All emitted PHP files land under generated/code/ mirroring the original namespace (e.g. generated/code/Magento/Catalog/Model/Product/Interceptor.php). Compiled DI configuration — the resolved argument map per area — lands under generated/metadata/ as serialized arrays. Both directories are gitignored; they are pure build artefacts that must be recreated on every deploy.

  5. 05

    Production autoloader picks up generated files instead of generating on first hit

    In developer mode, missing Proxy / Interceptor classes are generated on the fly during the first request that needs them — convenient but slow. In production mode that runtime fallback is disabled. The PSR-4 autoloader looks under generated/code/, finds the pre-built class, and loads it. Skip the compile step in production and you get a fatal "Class … does not exist" the moment the first request lands.

When to use

Four moments where you must run di:compile

Skip the compile step at any of these moments and your store either crashes or behaves in subtly broken ways. Treat each as non-negotiable.

  • Every production deployment (mandatory)

    Production mode disables the developer-mode runtime fallback. If generated/code/ is empty when the first request hits, Magento returns a fatal error. The compile step is therefore non-negotiable in any production CI/CD pipeline — alongside setup:upgrade and setup:static-content:deploy, this is the third leg of the deploy triangle.

  • After adding or changing any di.xml plugin/preference

    New plugin? Changed sortOrder on an existing one? Replaced an interface implementation via preference? The Interceptor source code Magento compiled earlier is now wrong. Re-run setup:di:compile so the freshly stitched plugin chain lands in generated/code/. Forget this and your new plugin appears to "not run" — because the Interceptor that used to know about it has been replaced by a stale one.

  • After installing a new module via composer require

    A freshly composer-required module ships with its own di.xml, plugins, and potentially Proxy targets. Magento has no idea about it until you compile. The deploy order is: composer require → setup:upgrade → setup:di:compile → setup:static-content:deploy. Skip the compile and the module is installed (DB schema and config in place) but its plugins never fire.

  • When debugging "Class … does not exist" errors

    Sometimes the compile cache is stale — a developer added a Proxy reference and a teammate pulled the change without re-compiling locally. Symptoms include Class Magento\Foo\Model\Bar\Proxy does not exist from nowhere. Delete generated/ entirely and re-run setup:di:compile. Ninety percent of phantom DI errors disappear after a clean rebuild.

Common mistakes

Three traps that turn a clean compile into a broken deploy

Every broken deploy I have been called in to fix made one of these three mistakes. Catch them early and the compile step becomes boring.

  • Compiling in production mode without deleting generated/ first

    Running setup:di:compile on top of an existing generated/ directory does not always overwrite stale Proxy classes — under some failure conditions the compiler leaves the old file in place. Symptoms: a plugin you removed appears to keep firing. Always delete generated/code and generated/metadata before each production compile. Make it the first line of your deploy script: rm -rf generated/code generated/metadata.

  • Constructor signature mismatch between parent and child

    When you extend a Magento core class and override the constructor, your child class signature must be a strict superset of the parent's — same arguments first, new ones after, all with type hints. Mismatch and the compiler dies trying to emit an Interceptor for the subclass with: Incompatible argument type: required type …. Read the error carefully — it tells you which argument index and which expected type. Then realign your __construct signature.

  • Skipping compile in CI / deploy pipelines

    A CI pipeline that runs composer install and setup:upgrade but skips setup:di:compile will ship a broken site to production. bin/magento app:config:status will refuse to start, returning a non-zero exit code that crashes the container. Always bake the compile step into the deploy job, and run it after setup:upgrade but before setup:static-content:deploy. The compile-first ordering matters because static-content-deploy reads compiled config.

Related concepts

Five neighbour concepts most readers want to look at next. Click through for the full deep-dive.

FAQ

Magento DI Compile — frequently asked questions

  • Do I need to run di:compile in developer mode?
    No. Developer mode generates Proxy, Factory, and Interceptor classes on the fly during the first request that needs them. That makes the first page hit slow but means you can change a plugin and refresh the browser without running any CLI command. The compile step is only mandatory in production mode, where the runtime fallback is disabled for performance. In default mode (the middle setting), behaviour is closer to production — compile is recommended though not strictly enforced.
  • How long does setup:di:compile take?
    Typical range is 30 seconds to 5 minutes depending on module count and machine. A clean Magento 2.4 Open Source install with ~10 paid extensions compiles in roughly 60 to 90 seconds on a modern dev machine. Adobe Commerce installs with B2B, page builder, and customer segments take 2 to 4 minutes. Enterprise stores with 40+ paid extensions and heavy customisation can hit 5+ minutes. CI runners are often slower because of cold disk caches — budget at least double your laptop time for the deploy job.
  • Why does my compile fail with "Incompatible argument type"?
    That error means a child class overrode a constructor without keeping the parent's argument order and types intact. Magento's compiler stitches an Interceptor by extending your class and forwarding constructor arguments — if your signature does not strictly extend the parent's, that forwarding becomes impossible. Fix: read the error to find the offending class and argument index, then realign your <code>__construct</code> to match the parent signature exactly. Add new arguments only after all the inherited ones, all with type hints.
  • Can I run di:compile in parallel?
    Yes. The command accepts a <code>--threads=N</code> flag (default is the value of <code>magento.compile.thread.count</code>, often 2). Bumping to 4 on a quad-core CI runner typically halves the wall-clock time. Bumping higher than your physical core count rarely helps and can cause memory pressure on small VMs. Example: <code>bin/magento setup:di:compile --threads=4</code>. Monitor memory usage the first time you bump threads; if PHP OOMs, scale back or raise the CLI memory_limit.
  • Does Hyvä affect compile output?
    No. Hyvä is a frontend theme + module package — it changes the storefront rendering layer but does not alter the DI mechanism in any way. The same Proxy, Factory, and Interceptor classes get generated regardless of whether the active frontend theme is Luma or Hyvä. Hyvä modules ship with their own di.xml files that the compiler picks up like any other, but the compile command, flags, and output directory are identical.
  • What's the order: compile then static-content-deploy, or reverse?
    Compile FIRST, then static-content-deploy. The static-content-deploy command reads compiled DI configuration when resolving themes, view models, and module dependencies — if you run it before compile, it falls back to runtime generation, which is slower and occasionally produces inconsistent output. Standard production deploy order: <code>setup:upgrade</code> → <code>setup:di:compile</code> → <code>setup:static-content:deploy</code> → <code>cache:flush</code>. Bake this order into every deploy script and never deviate.
Deploy review

Stuck on a di:compile error or broken deploy?

Send the failing log and your di.xml — I will diagnose the constructor mismatch, plugin conflict, or stale generated/ cache, then reply with the fix and the deploy-script change that prevents it next time. 24-business-hour turnaround.

Get a deploy review Hire me directly