I have used it as a fix for a few things but I feel as though I will never truly comprehend the issues until I understand what setup:upgrade is doing w/ the files behind the scenes. I've gone through A LOT of the docs on the magento website but none of them really answer what this command does, only specific situations to use it in combination with other commands.

Here is what I am curious about:
What does setup:upgrade do?
What are some scenarios where a person would use it?
Are there any circumstances in which someone should not use it?

Please explain this as thoroughly as possible.

Thank you.

  • could you please go ahead and accept my answer? Without getting my reputation points, there really isn't much motivation to provide you with FREE help. Thanks Commented Oct 25, 2016 at 10:33

2 Answers 2


setup:upgrade is used whenever you have installed a new module on your system. When you run this, Magento checks the setup_module table and it compares each module's schema_version and data_version against modules existing on your site. If any of the modules have a greater version number than the one on record in the setup_module table, the appropriate install script is run.

So the easiest way to understand it: any time you install a new module on your site, run it.

Other than that, I'm not sure what kind of 'fixes' you were able to use it for. Im guessing that there were modules that weren't installed on your site and after you ran it they became installed. If you were a user of Magento 1, you are likely used to modules installing automatically upon the first page load after they get added to your system, but Magento 2 does not work that way.

Thats it in a nutshell.

  • Does that mean when I construct my own custom theme in /var/www/magento2/app/design/frontend/<vendor>/custom-theme/ I have to use upgrade? Commented Oct 21, 2016 at 19:46
  • I haven't done a ton of theming, mostly I am doing backend work with collections, models, blocks, observers, plugins, etc. I would say that until you know for sure, you should run it as a failsafe. There is no harm in running it because it only runs what needs to be run. Commented Oct 21, 2016 at 19:48
  • If this explanation helped you, please remember to mark the answer as accepted so that other readers know it is valid. Commented Oct 21, 2016 at 20:09

Setup:upgrade is used to install a new module in the eCommerce store. When you run upgrade command then the module related information gets stored in the data base table. To have a look, go to phpmyadmin -> search your database name -> Search "setup_module" Table. You will be able to see module information such as Module Name, schema_version, data_version. I think I have resolved your query. For any other assistance, please let me know.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.