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.

Installation and updates are Composer-only. Since version 1.16.0, Composer is the only way to install or update any WeltPixel product, including the Pearl Theme. The theme is no longer provided as a downloadable package, and there is no self-serve file download in your account. If you are reading an older guide that tells you to download a theme pack and upload the files by hand, that approach is retired — use the Composer steps below instead.

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. If you only have one store view, ignore this.

!!!!! Important: Run the upgrade with Magento in developer mode, then switch back to production mode afterward. Learn how in this article.

Pearl Theme Upgrade Steps (Composer)

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. If you are still on a manual/SSH install, migrate to Composer first

If the theme is currently installed by hand (files in app/code/WeltPixel and app/design/frontend/WeltPixel), remove those old files before running any Composer command, otherwise Magento will see two copies of the same module and setup:upgrade / setup:di:compile will fail. Full walkthrough: Migrating from manual SSH installation to Composer Installation. If you are already on Composer, skip to Step 3.

Step 3. Get your Composer commands from your account

Log in to account.weltpixel.com (sign-in is passwordless — you will receive a one-time code by email), go to My Products, find the Pearl Theme, and click Enable Composer. The page shows the ready-to-copy Composer configuration and require commands for your account. Run them from the root of your Magento 2 project.

The Pearl Theme package is weltpixel/m2-theme-frontend-weltpixel. To pull the latest release, run the require command shown on your Enable Composer page (or composer update weltpixel/m2-theme-frontend-weltpixel if it is already installed).

If you purchased Pearl through Magento/Adobe Marketplace, the package may not yet be linked to your weltpixel.com account. In that case reach out to WeltPixel Support with your Marketplace order number, purchase date, and WeltPixel account email so the team can link it.

Step 4. Run the standard Magento setup commands

After Composer pulls the new version, run:

bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy
bin/magento cache:flush

(Run static-content:deploy with your store's locales if you are in production mode.)

Step 5. Verify the update

Go to Admin > WeltPixel > WeltPixel Debugger > Extensions Version and confirm the version matches the latest release.

That's it. You've updated the Pearl Theme via Composer.

Magento Commerce Cloud: commit the updated composer.json / composer.lock to your environment repository and let the cloud deploy pipeline apply the change, rather than running Composer directly on a read-only cloud node. See the official guides for the ideal-state and non-ideal-state environments.

Note: If you genuinely cannot use Composer in your environment, reach out to WeltPixel Support and the team will advise on the best option for your setup.

Updated on: 11/06/2026