How does Magento handle layout XML files?

For example if I have created a theme app/design/frontend/example/theme and copy an XML file from the base/default/layout directory in my theme's layout directory:

  • Does it override the whole file? Meaning will I have to copy the XML file into my theme to begin overriding things, or
  • Does it merge with the base/default and override only the changes I have made in my XML file?

1 Answer 1


In brief, this is how Magento loads layout files:

  1. When loading a theme, Magento reads the configuration of all the available modules, and checks which layout files should be loaded.
  2. For each file, Magento tries to load it from your theme.
    If it exists in your theme, it loads it and goes directly to step 4.
  3. If the file doesn't exist in your theme, it tries to load it from the base/default theme.
  4. Magento parses the XML files and merges them into one.
  5. Magento looks for a local.xml file in your theme, and appends whatever is there, to the previously merged layout handles.

So, unless absolutely required,

  • Use the local.xml for changing the layout of a theme, instead of copy/pasting the xml files from base to your theme.
  • Create your own layout files for your own custom modules.

It - almost - doesn't matter if a layout handle exists in foo.xml or bar.xml.
I've seen implementation where people copy/paste catalog.xml to their own theme, because they think that's the only place where they can edit "catalog-related" handles.
The difference you would notice between adding a handle in foo.xml instead of bar.xml, is that a block would be appended in a different order, depending on which layout file was first loaded.

  • Right, that's what I thought. Also, for example all of the core XML layouts are defined within their modules - i.e. Mage_Catalog defines catalog.xml which obviously does it's own layout stuff. I also understand how local.xml works - just i've been working on a site that's hacked to f**k and from what you've said, it sounds like my theme entirely overrides the base/default/layout files except what's inside of local.xml and any extensions XML which should really be extended (using: <depends/>) if they need to be customised.
    – Ash
    Jun 9, 2015 at 16:11
  • 1
    Good answer, but don't forget that you have the option to add a theme.xml file in Magento >=1.9 to change the fallback mechanism
    – Sebastian
    Jun 10, 2015 at 10:05

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.