I want to modify certain aspects of the out-of-the-box Luma theme but I would like to do it by preserving the original file(s) and also ensuring that whenever I update Magento I preserve my changes as well.

I want to do this by way of a Child Theme.

Does Magento 2 support child themes and, if so, how do I structure my directory path to make this happen?

  • 2
    I am grateful that you asked this question. I was wondering the same thing!
    – camdixon
    Commented Apr 4, 2016 at 2:52

3 Answers 3


Lets us create a child theme so our all custom themes in Magento 2 goes here:


Let us assume, our company name is mycompany and our theme name is basic. We need to create following directory structure for our theme:

                   │       └─layout
                   │             default.xml
                   │       preview.png
                   │  └─css
                   │  └─fonts
                   │  └─images
                   │  └─js
                   │ theme.xml
                   │ registration.php

mycompany :-

The name of the theme package

basic :- The name of the theme. We can have multiple named themes inside the mycompany folder.

etc/view.xml :-

This file is used to specify product image dimensions, thumbnails etc.

Magento_Theme :- This directory is used to override existing Magento’s theme files.

Magento_Theme/layout/default.xml :- By default Magento2 assumes that your theme’s logo file should be: /web/media/logo.svg If you want some other file for logo, then you must declare it in default.xml file.

This file is also used to override default theme’s settings.

media/preview.png :- The preview of current theme.

web :- This directory contains all the theme’s static data like images, styles, javascript, fonts etc.

registration.php :- This file is required to register our theme to Magento2 system.

theme.xml :- This is a compulsory file that defines our theme name, its parent and optionally theme’s preview image.

Creating theme files

Let us now create our files one by one.

theme.xml ( app/design/frontend/mycompany/basic/theme.xml )

<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
   <title>Basic</title> <!-- your theme's name -->
   <parent>Magento/blank</parent> <!-- the parent theme -->
        <preview_image>media/preview.jpg</preview_image> <!-- theme's preview image -->

registration.php ( app/design/frontend/mycompany/basic/registration.php )


default.xml ( app/design/frontend/mycompany/basic/Magento_Theme/layout/default.xml )

<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
        <referenceBlock name="logo">
              <argument name="logo_file" xsi:type="string">images/my_logo.png</argument>
              <argument name="logo_img_width" xsi:type="number">200</argument>
              <argument name="logo_img_height" xsi:type="number">200</argument>

At this point, our theme is ready. Clear your cache and we will now select our new theme from admin.

Now, login to admin and move to following path:

Content -> Design -> Themes

You should see your theme listed.

Now go to:

Stores -> Configuration -> Design

Choose Main Website in front of Store View at top left. Now click

Desgin -> Design Theme

Uncheck Use Default checkbox and pick your theme. Click Save Config, clear your cache and your new theme is ready. Check your home page.

For more detail see here.

  • Thank you for the extensive step-by-step guide @Arunendra. I will give it a try shortly and post back. Commented Mar 31, 2016 at 13:08
  • This is excellent @Arunendra. Worked perfectly. Just need to follow it completely without skipping any steps. Commented Mar 31, 2016 at 20:08
  • 2
    Great step-by-step @Arunendra. Just in case anyone runs into the same problems as me, the location where you apply your registered theme has changed from Design -> Design Theme to Content/Design/Configuration.
    – Kedmasterk
    Commented Jan 11, 2017 at 15:29
  • Important note: File media/preview.png must exist otherwise Magento will throw an exception.
    – Salman
    Commented Nov 10, 2018 at 6:32

Create directories:

Go to root to the root directory and navigate to app/design/frontend, create directory Demo.

Now create Mytheme directory in app/design/frontend/Demo.

Create Mangento_Theme directory in app/design/frontend/Demo/Mytheme.

Create layout directory in app/design/frontend/Demo/Mytheme/Magento_Theme.

Create media directory in app/design/frontend/Demo/Mytheme.

Create web directory in app/design/frontend/Demo/Mytheme.

Create images directory in app/design/frontend/Demo/Mytheme/web.

Declaration of Theme

Create theme.xml file in app/design/frontend/Demo/Mytheme, and paste the following code in it:

<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">

Registration of Theme

Now create registration.php file in app/design/frontend/Demo/Mytheme and paste the following code in it:

\Magento\Framework\Component\ComponentRegistrar::THEME, 'frontend/Demo/Mytheme', __DIR__

Upload Theme Preview Image

Go to app/design/frontend/Demo/Mytheme/media and upload your preview image (preview.jpg) here.

Declaration of Theme Logo

Go to app/design/frontend/Demo/Mytheme/Magento_Theme/layout and create a default.xml file. Paste the following code in it:

<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
<referenceBlock name="logo">
<argument name="logo_file" xsi:type="string">images/mytheme-logo.png</argument>
<argument name="logo_img_width" xsi:type="number">200</argument>
<argument name="logo_img_height" xsi:type="number">200</argument>

Upload Theme Logo

Go to app/design/frontend/Demo/Mytheme/web/images and upload your logo (mytheme-logo.png) here.

Apply Your Theme

  • Open the Admin panel of your Magento 2 and go to Content → Configuration.

  • Click on Edit option.

  • Select Mytheme from the Applied Theme drop down menu and click on
    Save Configuration.

Run Commands

Open SSH terminal and go to the root directory of your Magento 2. Now run all these commands one by one:

rm -rf var/di/* var/generation/* var/cache/* var/log/* var/page_cache/* var/session/* var/view_preprocessed/* pub/static/*
php bin/magento setup:upgrade
php bin/magento setup:db-schema:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy
php bin/magento indexer:reindex
php bin/magento cache:clean
php bin/magento cache:flush

I have created an extension to help you create a child easily from admin here https://github.com/magepow/magento-2-create-child-theme

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