← Tutorials

Joomla 4 to 5 Upgrade Guide & the Backward Compatibility Plugin

Migration · Joomla 4 → 5 · Updated June 1, 2026

Verify before production. Steps follow the official Joomla documentation (verified 2026-06-01). Test on a staging copy first. Note that Joomla 4.4 reached its security end-of-life on 14 October 2025, so upgrading is a security matter, not just a feature one.

✅ We actually ran this upgrade. On a live install we upgraded Joomla 4.4.14 → 5.4.6 on PHP 8.2: the database schema migrated automatically (172 changes), the Backward Compatibility plugin (plg_behaviour_compat) was present and enabled afterwards, and the site + admin came back healthy. Two real gotchas we hit are written up below.

Unlike the Joomla 3→4 move, going from Joomla 4.4.x to Joomla 5.x is an upgrade, not a migration. There is no separate migration tool — you update through the same Joomla Update component.

Requirements first

Joomla 5 needs:

  • PHP 8.1 (PHP 8.2 recommended) — note it is 8.1, not 8.2, a commonly repeated mistake.
  • MySQL 8.0.13+, MariaDB 10.4.x+, or PostgreSQL 12.0+.

If your server doesn’t meet these, the Joomla 5 upgrade option won’t even appear in the Update component. Check your stack first with the version & PHP compatibility tool.

The Backward Compatibility (B/C) Plugin

This is the key thing to understand about Joomla 5:

  • Extensions that are free of deprecated code work in Joomla 5 directly.
  • Most other extensions keep working through the Behaviour – Backward Compatibility Plugin, which is auto-enabled when you upgrade and enabled by default on fresh Joomla 5 installs.
  • The B/C layer is scheduled to be dropped in Joomla 6, which effectively gives extension developers about two extra years to update their code.
  • For best performance, the long-term goal is to disable the B/C plugin once all your extensions are fully J5-native.

Upgrade steps

  1. Back up files and database.
  2. Update to the latest Joomla 4.4.x release.
  3. Confirm your PHP and database meet the Joomla 5 requirements above.
  4. Switch the update channel. By default Joomla 4.4 only offers 4.4.x patches and will tell you “you already have the latest version.” Go to System → Update → Joomla, open Options, and set the Update Channel to Joomla Next. Joomla 5 will now appear as available.
  5. Run the update from System → Joomla! Update.
  6. Test thoroughly; review whether you can eventually disable the B/C plugin.

Heads-up: “Update finished with errors”

In our test, the update completed and the site worked, but the process reported “Update finished with errors.” The log pointed to the extension cleanup phase:

An error has occurred while running "uninstallExtensions". …
Joomla\CMS\Plugin\CMSPlugin::__construct(): Argument #1 ($subject)
cannot be passed by reference.

This happens while Joomla removes old extensions during the upgrade and is not fatal to the upgrade itself — the core files and database were still migrated. After seeing this:

  1. Confirm the version really changed (Home dashboard, or System → System Information) — it should read 5.x.
  2. Run Extensions → Manage → Database and click Fix if anything is flagged.
  3. Clear cache and test the front end and admin.

If the site is broken (not just a warning), restore your backup and retry, disabling third-party extensions first.

What about Joomla 6?

Joomla 6 is already the current major series. Once you’re stable on Joomla 5, keep an eye on the version compatibility tool for the right time to move on — and remember the B/C plugin goes away in 6.