MageQuest Logo
MageQuest Logo

Directory Structure

April 19, 2020

That's a lot of code...

To say Magento 2's codebase is fairly large is an understatement! If you're new to the platform, it's understandable to be overwhelmed by the sheer number of directories and files.

We'll start by taking a run through Magento 2's root (top-level) directory highlighting the main directories and files, before diving deeper into a few key areas.

We're using Composer

We'll be assuming that you have installed Magento 2 via Composer. If you've cloned Magento 2 from GitHub, then you'll find you may have slightly different contents to the below. For more detail on getting Magento installed using Composer, see Install & Setup.

Magento 2's root directory

One key thing to note, before we go any further, is that when you create a new Magento 2 project via Composer, you'll have a minimal set of files and directories. Only after you've run composer install will you see the full set of files/directories. This is because Magento 2 has a few customisations that run after composer install (or composer update) are run to auto-generate some of the files/directories (i.e. they are copied from within packages inside the vendor/ directory to the project root. We'll highlight these in the table below as well as recommendations for which areas to include within your version control (e.g. git).

Directory/FileContentsAuto GeneratedVersion Control


  • All of a projects source code (custom modules, themes and language packs)
  • Key configuration files (such as database credentials and active modules)
  • Bootstrap files (i.e. files perform the initial load of the application)

Yes (excluding your own project code)

Yes, but excluding auto-generated bootstrap and environment files with sensitive data


The bin/magento Command Line Tool (CLI) is the only file within this directory, which allows management of the Magento application from a terminal




  • Test files and Travis configuration
  • Tools, such as the grunt task runner for theme compilation during development


No, bar any custom grunt configuration


This directory contains code that is autogenerated by Magento as part of its Dependency Injection (DI) implementation

Yes (directory only, files are generated at runtime/compilation)



Internal and external library code and static assets, including:

  • Magento Framework
  • Magento UI Library (reusable LESS/CSS patterns)
  • External JavaScript libraries (jQuery, RequireJS, Knockout, Underscore and more)
  • Magento 2's internal JavaScript libraries (including extension/modification of external libraries)




Scripts that allow you to run Magento 2 via PHP's built-in webserver (not for production use, plus there are far better ways to create a development environment, as covered in Install & Setup)




Where all static assets from modules, themes and libraries are compiled per theme and locale for inclusion on the frontend (i.e. linked to from the HTML document), along with media (e.g. images) from products, categories and CMS pages

This directory also contains the error theme used when there is a problem with the application or 'maintenance mode' is enabled

This directory can also be the 'webserver root' directory and is recommended from a security perspective as means all other application code isn't accessible



setup/ and update/

Internal code that's focus is on assisting with installing and upgrading Magento 2 itself (i.e. the installed components)

Yes, however, update is itself a further package created during the composer create-project process and separate from the main Magento 2 application

setup/ - no

update/ - does not get re-generated so either version or manually update when upgrading Magento itself (see DevDocs for guidance)


Stores non-persistent files such as cache and session data (if using the filesystem to store), error and debug logs and data export files

Yes (



Where all external dependencies are installed as per any standard PHP application utilising Composer




The entry point file the Magento 2 application if the root directory is set as the webroot. As noted above pub/ should be set as the webroot for security reasons, and an equivalent index.php exists there (with updated paths to included files)




As with any Composer based PHP application, this file contains all your project-level dependencies. Any third party Magento components (modules etc.) or other packages installed via Composer are listed in this file.




Again, standard Composer based project file - this contains the exact versions of packages installed


Yes, ensures all collaborators (and your production environment) always have the correct version of all dependencies installed


An example file for adding your Magento Composer credentials to negate having to re-input these when running Composer commands. Copy this file and name it auth.json for Composer to pick it up


No (or auth.json as contains sensitive credentials)

The 'app' directory

As its name suggests (it's short for 'application'), this directory is where most of the 'action' takes place in Magento 2. As noted above all your project source code (would normally) live within this directory, but equally so do some of the other key files in regards to your project's configuration.



The home for all your projects custom modules, which would be found under further subdirectories by vendor and module name

e.g. app/code/MageQuest/MyModule


The place for any themes specific to your project, placed under further subdirectories for area*, vendor and theme name

e.g. app/design/frontend/MageQuest/my-theme

*Area, in this context, relates to frontend (storefront) or adminhtml (admin panel) themes


Where all project specific language packs are kept, within further vendor and language pack name subdirectories

e.g. app/i18n/MageQuest/en_GB

Language packs are usually named based on the locale (in this case en for English) and country code (in this case GB for Great Britain)


The home of application level configuration files


Contains an array (list) of installed modules, their status (i.e. are they enabled) and load order (determined by the order of the modules)

Modules and their order/status are auto-generated in this file based on running certain bin/magento setup and module specific commands, they should never be manually edited

You can also set other store configuration values in this file (such as the websites/stores active on the site and their names, or active payment methods, for example)
Adding them to this file causes them to not be editable in the Magento admin panel


The environment configuration file - it contains:

  • Database (MySQL) credentials
  • Caching and session storage connection settings
  • Cache types and status
  • Application mode (normally production or developer)
  • Admin URL path
  • Encryption key (used to encrypt/decrypt sensitive data stored within the database)


Default (application level) Dependency Injection (DI) configuration

e.g. which logging tool* is used across the system

*Monolog is the default if you're curious!


DB schema files are concerned with the structure of the MySQL database

This file manages schema that is not specific to a particular module, but the entire application itself

At present, the only schema managed in this file is a table that manages whether schema/data patches (patches that modify database structure or data within it) for installed modules have been applied


The file that initialises the Magento 2 application


Manages including Composers autoload functionality (and is included itself via the bootstrap.php file)