719-286-0751 [email protected]

Magento 2 When Should You Run setup:di:compile ?

One of the most common questions I receive from new developers on my team is, when (and why) do I have to run the below command:

bin/magento setup:di:compile

What does this command do?

This command is responsible for a variety of tasks. Looking at Magento’s official docs we can see it’s responsible for 2 different categories of tasks:

Code Generation

Magento 2’s robust plugin system and dependency injection works by creating generated php source code based on the non-generated code you write. This includes classes for:

  • Interceptors — Classes that modifies the behavior of a public function call by running code either before, after, or around that function.
  • Factories — Classes that instantiate non-injectable classes
  • Proxies (virutal classes) – Classes which are used to allow for lazy-loading of dependencies.
  • Repositories code generation – generated code for the API
  • Service data attributes generation – generated extension classes

These components must be present in order for Magento 2 to function

Code Compilation

“Compilation” in this term really should be called “optimization” in my opinion. As far as I can tell, this mostly consists of:

  • Aggregating all area specific dependency injection (DI) configurations into .ser files located in var/di/

These are essentially caches of configuration information for the DI functionality, and Magento can be run in developer mode without them

Running setup:di:compile

Running this command will compile the DI configuration and generate all the code listed above.

It’s slow — when should I run it?


As you’ve undoubtedly realized, it’s quite slow to run this command. For that reason, this command should only be run when deploying new updates to your production environment, or running an application in production mode. Unfortunately there is no way around running this command when the app is in production — the performance boost from pre-compiling / pre-generating all the code is simply too great to keep the app in developer mode on a live site.


This command does not need to be run when the app is in developer mode. Magento uses automatic code generation when the app is in this mode, and if it can’t find a generated class it creates it on the fly.

Running setup:di:compile places the app into a special mode

If you do run setup:di:compile — even with your app in developer deployment mode — you will place the application into a special Compiled mode. Note the file:

## file vendor/magento/framework/App/EnvironmentFactory.php
namespace Magento\Framework\App;

class EnvironmentFactory

     * Determinate running mode
     * @return string
    private function getMode()
        if (file_exists(ConfigLoader\Compiled::getFilePath(Area::AREA_GLOBAL))) {
            return Compiled::MODE;

        return Developer::MODE;

You’ll notice that this function checks for files like var/di/frontend.ser or var/di/adminhtml.ser and if they’re found, puts the app in a different mode.

Here’s the big difference, in developer mode:

  • Changes to DI configuration or method signatures require you to delete var/generation
  • Compilation is not needed for the app to run, and aside from occasionally deleting this directory, no commands are needed.

In the Compiled mode:

  • Any changes to the DI configuration or method signatures require you to run setup:di:compile

If you run setup:di:compile, you will be forced to continue running the command to see your DI changes come through, even in developer mode.

Deleting folders

As I mentioned in the above section, there are certain times when you need to delete the var/generation folder — Luckily, Magento 2 has a great article on when you need to clear them here. 

Cadence Labs also has an experimental module to handle flushing the generated files for you: click here to read the article.

About Cadence Labs

Cadence Labs is an ecommerce design and development agency located in Boulder, Colorado.

If you would like assistance, or for a free consulation, call (719)-286-0751 or visit our contact page to have a real person contact you today!

Alan Barber is the Lead Web Developer at Cadence Labs and a Magento Certified developer.

1 Comment

  1. Ray

    Very well documented instructions. Thank you for the explanation.



  1. Magento 2 Development Environment Performance | Land Digital - […] (again, you’ll see a lot of people advising you to do this). As the good folks at Cadence Labs…

Submit a Comment

Your email address will not be published. Required fields are marked *

Install our webapp on your iPhone! Tap and then Add to homescreen.
Share This