In Magento 2 Theme , default.xml and default_head_blocks.xml files are located in app\design\frontend\{package}\{theme}\Magento_Theme\layout

can anyone tell me what is the difference between these two files ?

3 Answers 3


default.xml: defines the page layout.

default_head_blocks.xml: defines the scripts, images, and meta data included in pages’ section.

You can read more about this here: from magento doc

Example of default_head_blocks.xml


<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
        <!-- Add local resources -->
        <css src="css/my-styles.css"/>
        <!-- The following two ways to add local JavaScript files are equal -->
        <script src="Magento_Catalog::js/sample1.js"/>
        <link src="js/sample.js"/>
        <!-- Add external resources -->
    <css src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap-theme.min.css" src_type="url" />
        <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js" src_type="url" />
        <link rel="stylesheet" type="text/css" src="http://fonts.googleapis.com/css?family=Montserrat" src_type="url" /> 

Example of default.xml


<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
        <referenceContainer name="sidebar.additional">
            <block class="Magento\Catalog\Block\Product\Compare\Sidebar" name="catalog.compare.sidebar" template="product/compare/sidebar.phtml"/>
  • Thanks for replay but we can also use head section in default.xml also so why default_head_blocks.xml concept has come. Commented Sep 13, 2018 at 9:52
  • When you will add js and css using default_head_blocks.xm it will be add for all pages and in default.xml with in every module head will be for that module specific Commented Sep 13, 2018 at 9:54
  • like as some thing you want to add in head for catalog section only then you will use default.xml inside Magento_Catalog. Commented Sep 13, 2018 at 9:56

The basic view of all Magento storefront pages in defined in two page configuration layout files located in the Magento_Theme module:

1) <Magento_Theme_module_dir>/view/frontend/layout/default.xml: defines the page layout.

2) <Magento_Theme_module_dir>/view/frontend/layout/default_head_blocks.xml: defines the scripts, images, and meta data included in pages’ <head> section.

These basic page configuration layouts are extended in other Magento modules and in Magento themes.

You can also extend or override these files in your custom theme.

REF https://devdocs.magento.com/guides/v2.0/frontend-dev-guide/layouts/layout-overview.html

  • Thanks for you answer,but we can also define head section in default.xml so why concept of default_head_blocks.xml has come Commented Sep 13, 2018 at 9:47
  • @SanjayShiyal It's basic separation of responsibility. One adds the markup and the other adds the look and feel. It's like breaking the code in two functions or separating the logic in two classes. Commented May 24, 2019 at 20:08

default_head_blocks.xml is a specific layout of head section, and this file is called in default.xml : <update handle="default_head_blocks"/> so if you want to add in head section css, javascript, static assets, The recommended way is to add them in default_head_blocks.xml.

You can very well add them in default.xml one and it works, but your code you will not be pretty as Magento do, Since we use Magento, we should apply the recommended way.

JavaScript, CSS and other static assets are added in the section of a page configuration file. The default look of a Magento store page is defined by app/code/Magento/Theme/view/frontend/layout/default_head_blocks.xml. The recommended way to add CSS and JavaScript is to extend this file in your custom theme, and add the assets there.


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.