How to override media.phtml in my custom magento module?

How to override media.phtml in my custom magento module?

September 6, 2026 · Illustrated author avatarBy Stefan Bogdanescu
How to override media.phtml in my custom magento module?

Overriding media.phtml in Your Custom Magento Module

In this post, we’ll walk through how to override the media.phtml template within your custom module for Magento 2. This is a common requirement when you need to customize the product view page to load images from an external server or apply specific styling.

Understanding Template Overrides in Magento 2

Magento 2 uses XML layouts and themes to manage template overrides. When creating a custom theme, templates are located in app/design/frontend/<Vendor>/<Theme>/template.

For your module-specific overrides, you should place the modified files under app/code/<Vendor>/<Module>/view/frontend/templates/catalog/product.

Step-by-Step Guide to Override media.phtml

1. Create the Overridden Template in Your Module

First, create a directory structure that matches Magento’s default template path:

/app/code/<Vendor>/<Module>/view/frontend/templates
/app/code/<Vendor>/<Module>/view/frontend/templates/catalog
/app/code/<Vendor>/<Module>/view/frontend/templates/catalog/product

Then, place your modified media.phtml file inside the product directory.

Your updated code should look like this:

<!-- app/code/<Vendor>/<Module>/view/frontend/templates/catalog/product/media.phtml -->

<div class="product-img-box">
    <!-- Your custom media markup here -->
</div>

2. Update XML Layout to Apply Your Override

Next, update your module’s default/view/frontend/layout/catalog_product_view.xml file:

<!-- app/code/<Vendor>/<Module>/view/frontend/layout/catalog_product_view.xml -->

<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceBlock name="product.info.media" template="Magento_Catalog::catalog/product/view/media.phtml" />
    </body>
</page>

In this example, we are referencing the product.info.media block and applying our custom media.phtml template.

3. Check Your Override in Action

After making these changes:

  • Recompile your Magento store using the command php bin/magento setup:static-content:deploy -f.
  • Make sure to clear cache by running php bin/magento cache:flush.

Now, when you view a product page, you should see your custom media.phtml template in action.

Best Practices and Additional Resources

  1. Always create a dedicated theme for your module-specific templates.
  2. Avoid modifying core files directly; create an override instead to maintain update compatibility.
  3. Use version control systems like Git to keep track of changes made to your custom templates.

For further reading on Magento 2 template overrides, check out the official documentation: https://docs.magento.com/user_guide/stores/theme-override.html

Conclusion

In this post, we demonstrated how to override media.phtml within your custom Magento 2 module. By following the steps outlined above, you can successfully apply your own media markup and styling for product images.

Remember, always keep your code organized, version-controlled, and tested thoroughly before deploying changes in a production environment.

Happy coding!

Magento 2 Catalog Extensions Themes

Our network