Joomla 3 to Joomla 4
Prev Chapter 3. Migrating from old versions of Akeeba Backup and Joomla! Next

Joomla 3 to Joomla 4

[Important]Important

We only provide a migration path from Joomla 3.10 to Joomla 4. If you are using an earlier Joomla 3.x version please upgrade to Joomla 3.10 first.

You cannot migrate from Joomla 3 to Joomla 5 or later. You will need to migrate to Joomla 4 first.

On your Joomla 3 site

Make sure you have Joomla 3.10

Migration from Joomla 3 to 4 is only supported by the Joomla project if you are already running Joomla 3.10. If you are not already on Joomla 3.10 please upgrade to Joomla 3.10, and upgrade all of your extensions —including Akeeba Backup— before proceeding.

Check your PHP versions

Make sure that your server is using PHP 7.2, 7.3, 7.4, 8.0 or 8.1. These are the only PHP versions which are supported by both Joomla 3.10 and Joomla 4.0–4.3. Older PHP versions will not let you upgrade to Joomla 4 at all. Newer PHP versions will not let you run Joomla 3 at all (it will keep receiving errors). The latter is important if you are restoring a backup to a dev server.

We recommend using PHP 7.4, 8.0 or 8.1 if possible.

Make sure Akeeba Backup is up to date

Go to Extensions, Manage, Manage.

Search for Akeeba Backup package.

Check what is the version displayed for the Akeeba Backup package item. If it does NOT start with 8. you will have to update Akeeba Backup. In this case go to our Compatibility page and download the version for your Joomla and PHP version. Install the ZIp file you downloaded from Extensions, Manage, Install, Upload Package File. You will need to install this file twice in a row, without uninstalling your current Akeeba Backup version before or in between.

[Tip]Tip

If you are not sure which version of Joomla and PHP you are using go to System, System Information. Look at the PHP Version and Joomla! Version rows.

Disable plugins
[Note]Note

This is an optional step. It is recommended to do it anyway, to minimise the chance of any Joomla upgrade issues.

Go to Extensions, Plugins.

Find and disable the following plugins. Note down which of these plugins were already enabled. You will need it in a later step.

  • Action Log - Akeeba Backup

  • Installer - Akeeba Backup Professional

  • Quick Icon - Akeeba Backup Notification

  • System - Backup on update

Use our Magic Eraser

Our software has been around since Joomla 1.0. There are several “helper” extensions (libraries, frameworks, common features) we had created and used at some points in time which are no longer necessary and need to be removed. Instead of having you remove everything manually we have created an automatic method to clean up your site from our leftover extensions published between 2010 and 2021.

  1. Go to https://github.com/akeeba/magiceraser/releases/latest and download the item file_magiceraser-1.0.1.zip (the actual version number may be different).

  2. Go back to your site.

  3. Go to Extensions, Install, Upload & Install.

  4. Install the ZIP file you downloaded above.

  5. Ignore any warnings and the error that the file could not be installer. The latter is expected. Nothing is meant to be installed on your site. We are simply using Joomla's pre-installation script feature to run our custom clean-up script and then tell Joomla to abort the installation of our (fake) package.

Executing the update

Make sure that you have followed any pre-update steps necessary for all of the extensions on your site. Do keep in mind that this document only talks about Akeeba Backup, not any other extension from our company or a third party.

Take a full backup of your site and store it somewhere safely, outside of your web server. Ideally, keep two copies on separate media, e.g. a copy on your computer and a copy on a removable hard drive or USB flash drive.

[Warning]Warning

Your backup may consist of several files with the same name and extensions .j01, .j02, …, .jpa; or .j01, .j02, …, .jps; or .z01, .z02, …, .zip. You must download ALL of these files to have a complete backup of your site.

Whether you have one or multiple files for your backup can be determined by going to Components, Akeeba Backup, Manage Backups. Find the backup record and click on the Download button. If you see a single Download button in it there is just one file (.jpa, .jps, or .zip). If you see multiple buttons there are multiple files.

  1. Go to Components, Joomla Update.

  2. Click on Options.

  3. Change the Update Channel to Joomla Next.

  4. Click on Save & Close.

  5. Click on Check for Updates.

    [Note]Note

    You may see a few items marked as Update Information Unavailable or Update Required. If any of these are related to Akeeba Backup: ignore them. There are at least two different bugs affecting this page we reported to the Joomla project between August 2020 and August 2021. At the time of this writing (October 2022) they are still not fixed and there is no information as to whether they will ever be fixed.

  6. Click on the Live Update tab and proceed with the update.

If the update failed

Delete all files and folders. This is a very important step! If you forget to do it you will end up with a mix of Joomla 3 and Joomla 4 files which results in a broken site.

Upload kickstart.php (Akeeba Kickstart Core) and the backup archive file or files.

Follow the instructions on restoring a backup to restore your site.

Prev Up Next
Joomla 3 minor version updates Home After upgrading to Joomla 4