How to upgrade an add-on to a new version

Upgrading an add-on works like installing it. Upload the new version's files over the old ones, then click Upgrade in the Admin CP. Your settings, permissions and the add-on's data stay where they are, and XenForo runs whatever changes the new version needs.

Before you upgrade

• Read what changed. The Version History tab on each product page lists the changes in every release. Watch for notes such as "Needs XenForo 2.3" or a new setting you should look at.
• Check it suits your forum. The Compatibility section shows the XenForo version the new release needs. Find your XenForo version.
• Take a backup. It takes minutes and lets you undo anything. How to back up your forum.

Free add-ons download from their product page. Premium add-ons download from My Licenses while your update period is active. How updates and renewals work.

Upgrade from the Admin CP

1. Unzip the new version and open its upload folder.
2. Upload the contents of upload into your XenForo root, exactly as when you installed it. Let your FTP program overwrite every file.
3. In the Admin CP, open Add-ons. The add-on now appears under Upgradeable add-ons.
4. Click Upgrade, confirm, and keep the tab open until the progress page finishes.

If you have enabled the archive installer, Install/upgrade from archive on the same page takes the zip directly. How to install a XenForo add-on explains how to switch it on.

Tip: Upload every file in the new version, not just the ones you think changed. XenForo checks the files against the version you are installing, and a half-uploaded add-on is the most common cause of a failed upgrade.

Skipping versions is fine

You do not need to install each release in between. Going straight from 1.0.3 to 1.1.5 works: XenForo compares the version you have with the one you uploaded and runs every upgrade step between them, in order. Reading version numbers explains how it knows the order.

The exception is moving to a new major XenForo version. If a release notes that it needs XenForo 2.3, upgrade XenForo first. Upgrading from XenForo 2.2 to 2.3.

If the upgrade stops

These are the messages you are most likely to see, and what they mean:

• "The add-on files do not appear to be from the correct version. Please re-upload the correct files." Some old files are still in place. Upload the whole upload folder again, overwriting everything.
• "Some files or directories for this add-on are missing" Part of the upload failed. Upload again, then run the file health check to confirm nothing is missing.
• The progress page times out. Large forums can hit the browser's time limit. Run the upgrade from the command line instead, where there is no limit. Upgrade from the command line.

For any other message, Common add-on installation errors covers the rest.

After upgrading

• Open a page where the add-on appears and check it works as before.
• If you use a custom style, look at Appearance > Outdated templates and the template modification log. An upgrade can change a template your style has customized. Template modification errors and outdated templates.
• Still seeing the old version? A cache may be serving old files. Changes not showing?

Still stuck? Open a support ticket with the version you upgraded from, the version you upgraded to, and the exact message you saw.