In this section · 10 articles

Upgrade an add-on

Move an installed add-on to a newer version, either by uploading its new ZIP or by applying files already updated on the server. Review the changes and any breaking notes before you confirm.

Applies to
Core 12.0 and later
Who can do this
Platform owner
Permission
feature.core.addon.upgrade
Where
Addons › Addon Management
On this page

Before you start

  • You need feature.core.addon.upgrade, and feature.core.addon.install to upload a ZIP. By default only super admins have them.
  • If a Core upgrade is also waiting, run it first. See Run a system upgrade. Core comes first, then the add-ons.
  • Back up your database. An upgrade runs the add-on's new database migrations.

A newer version reaches Laramin in one of two ways. Follow the steps for yours.

If you have the new ZIP file

Uploading a ZIP for an add-on that's already installed upgrades it.

  1. In the sidebar, open Addons › Addon Management.

  2. Select Upload Addon.

  3. In Addon package, choose the new ZIP file, then select Upload.

Laramin checks the package before it changes anything:

  • A paid add-on's license must be active. Otherwise you see Upgrade blocked: an active licence is required for this add-on. This applies to both ways of upgrading. Free add-ons don't need a license.
  • The version in the ZIP must be newer than the installed one. Otherwise you see Uploaded version (…) is not newer than current version (…).
  • If the new version needs a newer Core, you see Addon upgrade requires system version … or higher.
  • Other add-ons must still be compatible with the new version.

Laramin then copies the add-on's current files to a backup, unpacks the new ones, and runs the migrations, upgrade seeder and publishing steps. If anything fails, it restores the old files and version and shows Upgrade failed. System was rolled back. Error: …

When it succeeds, the message still reads Addon Blog imported successfully. Check the Version column to confirm the new version.

If the files were updated on the server

When someone updates an add-on's files directly, for example over FTP or Git, its row shows Upgrade Available.

  1. In the sidebar, open Addons › Addon Management.

  2. In the add-on's row, select Upgrade (the arrow-up icon).

  3. In Review upgrade, check the version change, for example v1.2.0 → v1.3.0.

  4. Read any warnings:

    • This upgrade conflicts with a dependency lists what would break. You can't confirm the upgrade until it's resolved.
    • This upgrade includes breaking changes lists what works differently afterwards. This release includes upgrade / migration notes (UPGRADE.md). means the package has written upgrade notes. Read them first.
  5. Read What's new for each version you're about to install. A version marked Breaking changes how something works.

  6. Select Confirm upgrade.

Laramin runs the new migrations and upgrade seeder, publishes the add-on's assets, updates its permissions, runs its upgrade steps, rebuilds the sidebar, and checks that it loads correctly. Only then does it record the new version. You see a message such as Addon Blog upgraded to version 1.3.0.

If a step fails, you see Upgrade failed: … with the reason. Laramin undoes the database changes this upgrade made and keeps the old version, so the row still shows Upgrade Available. It can't put back the old files, because they were replaced on the server before you started. Fix the cause in the error, then select Upgrade again.

If a new version has no database changes, Laramin may record the new version by itself, and the row never shows Upgrade Available.

What happens next

The Version column shows the new version. To read what changed, open the module's history in What's new. If the upgrade didn't go through, see An add-on is stuck, failed or won't upgrade.