How do I upgrade from Joomla 5 to Joomla 6?

Why it is more than a normal update

Joomla 6 is a major version. It removes old code that was marked as outdated in Joomla 5, and it needs PHP 8.3 or newer. Joomla itself upgrades cleanly, but a template or extension that still uses the removed code can break your site's front end, its administrator, or both.

There is also no undo button: once the database is upgraded, the only way back is a backup. That is why the official guide puts testing and backups before anything else.

Before you start

• Joomla 5.4. The upgrade is only offered from the latest 5.4 release. On an older 5.x version, update to 5.4 first.
• Server requirements. PHP 8.3 or newer (8.4 recommended), MySQL 8.0.13+ or MariaDB 10.4+ (10.6 or newer recommended). Check them in System → System Information. If your server is too old, the Joomla 6 option simply doesn't appear.
• Your extensions. Go through System → Manage → Extensions and check every third-party extension and your template on its developer's site. Don't rely on the Pre-update Check alone.
• A test copy. Restore a backup on a subdomain or your own computer and do the upgrade there first. Note every step you needed.
• Database access. Make sure you can open phpMyAdmin (or ask your host). If an extension locks you out of the administrator, you switch it off in the database.

Step by step

1. Update every extension that has an update in System → Update → Extensions.
2. Disable or uninstall extensions that aren't ready for Joomla 6.
3. Turn on Debug System in System → Global Configuration → System, so you see the real error if something fails.
4. Make a full backup (for example with Akeeba Backup), download it, and test that it restores.
5. Open System → Update → Joomla, click Options, set Update Channel to Joomla Next, and click Save & Close.
6. Read the Pre-update Check. Required and Recommended Settings should pass. The Extensions section may show warnings even for extensions that work; your test copy tells you which ones really matter.
7. Turn off the plugin Behaviour - Backward Compatibility (the one without a number) in System → Manage → Plugins. Joomla turns on Behaviour - Backward Compatibility 6 for you during the upgrade; the two can't be on at the same time.
8. Tick the box to confirm the extension warnings, click Update, and wait until the success screen appears.

After the upgrade

• Check that the top-right corner of the administrator shows Joomla 6.
• Click through the front end and the administrator: menus, forms, logins, your most important pages.
• Turn Debug System off again.
• If search results look wrong, rebuild the Smart Search index (Components → Smart Search → Index).
• Leave Behaviour - Backward Compatibility 6 on until every extension says it is built for Joomla 6. Turning it off too early can break the site.

Good to know

• You don't have to rush: Joomla 5 gets security fixes until 12 October 2027. Wait until your template and key extensions are ready for Joomla 6.
• No Joomla 6 option in Joomla Update almost always means the server (usually the PHP version) doesn't meet the requirements yet.
• Extensions written for Joomla 5 keep working in Joomla 6 through the compatibility plugin, but Joomla 7 will drop it. Replace them during the Joomla 6 years.