Upgrade from Joomla 3 to 4

joomlaAt the time of writing, Joomla 3 has been the stable version of Joomla for 9 years. However Joomla 4 was released August 2021 and Joomla 3 will reach end of life in August 2023. This article describes how to upgrade to J4.


It is good practice to backup at each stage of the upgrade process.

  1. Start by creating your first backup, prior to upgrading to Joomla 4.


Separate domain

I recommend testing your upgrade, by using a separate subdomain (e.g. j4upgrade.yourschool.org). Using the backup created in the previous step, you can restore your website to this separate subdomain.

  1. Restore using Akeeba Kickstart.
    1. Browse to j4upgrade.yourschool.org/kickstart.php
    2. Enter database credentials.
    3. Site Parameters > Live Site URL: https://j4upgrade.yourschool.org
    4. Override tmp and log paths.
    5. Close the tab.
    6. Click Clean up button.

I use AdminTools, which meant that I also needed to manually edit the .htaccess file, and change yourschool.org to j4upgrade.yourschool.org.

I also needed to clear the cache on the server, after I completed the restore and I disabled NGINX direct delivery.

Pre-Update Check

Prior to upgrade you will need to check all your extensions for compatibility with Joomla 4.

  1. Go to Components > Joomla! Update.
    1. Click the Options button.
    2. Change the Update channel to Joomla Next.
    3. Click Save & Close.
  2. Update to the latest Joomla 3.10 version (3.10.11 at the time of writing).
  3. Click Check for updates button.

The Joomla! Update page will now show a Pre-Update Check for Joomla 4. Here are some steps that I had to complete:


Update Information Unavailable

I needed to uninstall any third-party extensions that appear in this section. I had the following:

  • System – nfrPiwik
  • file_fof30
  • System – SEO-Generator


Update Required

I also had a few extensions that simply needed to be updated to the latest versions.

Everything was now green apart from a warning that PHP was set to display errors.


Upgrade to Joomla 4

I was now ready to upgrade to Joomla 4

  1. Go to Components > Joomla! Update.
  2. Select the Live Update tab.
  3. Click the Install the Update button.

It reported that ReReplacer wasn’t compatible with Joomla 4. I subsequently  uninstalled the ReReplacer plugins and component, and reinstalled a newer version.


Module positions

All my modules were using the wrong positions. I went in and selected appropriate Cassiopaeia positions.

At this stage it became apparent that Gtranslate module needed to be deleted, and I reinstalled the latest version of Gtranslate.

Search has been replaced with Smart Search, and I needed to enable the smart search content plugin

  1. Go to System > Plugins.
    1. Enable the Content - Smart Search plugin.
  2. Go to Components > Smart Search > Index
    1. Click the Start the indexer button.


Cassiopeia menu settings

Edit the Menu module in the backend:

  1. Go to Content -> Site Modules.
  2. Open the Main Menu for editing
    1. Set the Position to menu.
  3. Select the Advanced tab.
    1. Set Layout to Collapsible Dropdown or Dropdown


Extensions > Update

Check to see if any of your extensions have an upgrade.

  1. Go to System > Update > Extensions.
  2. Click the Check for Updates button.

I found that AdminTools had an upgrade.

Akeeba Backup 8 is only meant to allow the upgrade process to keep existing backups:

  1. Go to System > Install > Extensions.
  2. Install Akeeba backup 9.
  3. Then click Components > Akeeba Backup for Joomla! > Control Panel.
  4. Click the Migrate settings button.
  5. Once the migration is complete you can click the Show me what to uninstall button to remove Akeeba 8.


Final configuration checks

Here are some more configuration checks that you might need to do.

  1. If you use Matomo for analytics, you might need to install the tracking code.
  2. If you haven't done this before, now might be a good time to remove article IDs from URLs.
  3. Configure the Cassiopeia template with your own branding.


Move back to production site

Once you are happy with all updates, you can migrate your site back to its production location.


Thanks for visiting,