How can I upgrade/update the Pearl Theme to the latest version?
When a Pearl Theme update is released, it’s strongly recommended to install it since new versions contain added features and fixes for reported issues. To avoid potential problems, follow the upgrade process outlined below.
Prerequisites before the upgrade
! Important: Always back up your code and database before performing an upgrade.
!! Important: If you extended the theme with customizations, ensure those are placed in a Child Theme so your changes are not lost. By following Magento best practices and using a child theme, Pearl Theme remains update-proof.
!!! Important: If you have translation files, copy them back into the correct location after the update.
!!!! Important: If you’re using Pearl Theme on multiple store views, follow these instructions. Store view functionality has been improved since release 1.5.5 (October 20, 2017). If you only have one store view, ignore this.
!!!!! Important: Ensure Magento is in developer mode before upgrading. Learn how in this article.
Pearl Theme Upgrade Steps
Step 1. Check the current version
Go to Admin > WeltPixel > WeltPixel Debugger > Extensions Version and compare your installed version with the latest release. If your version is lower, continue with the update.
Step 2. Download the latest version files
Log into your weltpixel.com account and download the latest Pearl Theme Pack under Downloadable Products.
If purchased from Magento Marketplace, see this article for file access. Marketplace versions are usually delayed by 1–2 months due to their review system. If you don’t want to wait, contact WeltPixel Support with your Magento Marketplace order number, purchase date, and WeltPixel account email.
If using Enterprise Cloud Edition, skip to the official guides:
Step 3. Disable Magento caches
Go to System > Cache Management > Select All > Disable, then refresh caches. This step is required even if cache is already disabled.
Step 4. Remove old files
It’s important to replace, not overwrite, old files to avoid leftover, outdated code.
Remove:
- Theme files under ``/app/design/frontend/Pearl/weltpixel``
- Dependencies under ``/app/code/WeltPixel/``
Do not remove unrelated WeltPixel extensions (e.g., Maxmind, GA4).
Step 5. Upload the new files
Unzip and merge the Theme Files directory into the root of your Magento installation.
⚠️ Make sure you use the correct directory for your Magento version:
- Magento 2.0.x–2.2.x
- Magento 2.3.x
- Magento 2.4.x
If you have a child theme at ``app/design/frontend/Pearl/weltpixel_custom/``, delete the weltpixel_custom folder from the new package before uploading.
If running Magento 2.3.0–2.3.2, copy the Patches folder and choose Overwrite.
If your server uses pub as the index folder, move the installation folder inside pub/ to avoid frontend 404 errors.
If using FileZilla, check for Failed Transfers and requeue them.
For Enterprise Cloud Edition (ECE), re-apply the ECE patch after updating and commit code to your repository.
Step 6. Run the installer/updater
Visit ``www.yourmagentostore.com/pearl-theme-installation/`` and follow the steps in the GUI installer.
Skip theme configuration steps (4–6) if you want to keep your current settings.
Step 7. Verify the update
Go to Admin > WeltPixel > WeltPixel Debugger > Extensions Version and check that the version matches the latest release.
Step 8. Re-enable caches
Go to System > Cache Management > Select All > Enable.
🎉 That’s it! You’ve updated the Pearl Responsive Theme.
Note: If hosting on AWS with Bitnami, see this article for fixing file permission issues.
Updated on: 17/09/2025
Thank you!