How to install a XenForo 2 add-on from an archive

XenForo add-ons ship as an archive containing an upload/ folder and an addon.json. The files go in first, the install comes second, and doing it in the other order is the mistake everybody makes once.

1. Back up first

Database dump plus a copy of src/addons/, js/ and styles/. XenForo also writes to data/ and internal_data/, so those need to be writable (755, and the files inside owned by the web user) before you begin.

2. Put the files in place

Unzip the archive on your machine. Inside you will find upload/. Copy the contents of upload/ into your forum root, merging with what is already there so that:

/src/addons/Vendor/Addon/…
/js/vendor/addon/…
/styles/…

Do not copy the upload folder itself into the root — that gives you /upload/src/…, which XenForo will never look at.

3. Install it

ACP → Add-ons → Install/upgrade from archive → upload the add-on archive (the one containing addon.json) → follow the prompts.

On a server you have shell access to, the same thing without the upload:

php cmd.php xf:addon-install Vendor/Addon

and afterwards, if anything looks stale:

php cmd.php xf:rebuild-caches

4. Permissions and options

Many add-ons register their own permission entries. Grant them under Groups & permissions — an add-on that is installed but invisible to your members is nearly always a permission, not a bug.

Removing an add-on

ACP → Add-ons → the add-on → Uninstall. XenForo asks whether to keep existing data; read the prompt instead of clicking through it, because "no" deletes the add-on's tables.

Then delete the folders listed in the add-on's addon.json if they are still there, and rebuild caches.

If the ACP says the add-on is not compatible

Add-ons declare a supported XenForo version range. Installing outside it is not supported and often half-works, which is worse than failing — it leaves rows behind that the next version trips over. Take the version the add-on was built for, or wait for its author.