Migration
Joomla 3 to 4 Step by Step
Introduction
Warning: This guide assumes you are starting on Joomla 3.10.x. If you are on an earlier version make sure you upgrade to Joomla 3.10 first before moving to Joomla 4. There is no rush. Make sure all your extensions are ready for Joomla 4.x. Joomla 3.10.x is supported until 16 August 2023.
The following are step by step instructions to migrate a 3.10.x site to Joomla! 4.x. While there are hundreds of different scenarios, this will give you the basic procedure to follow. Very complex migrations will likely be a result of installed third-party extensions. You are encouraged to contact the developers of third-party extensions installed on your Joomla site for their suggested path to migrate their extensions.
Step by Step
Set up a Development Location
- Make sure you are running the latest Joomla 3.10.x version before proceeding.
- Take a backup of your live 3.10.x site. You can use a suggested tool (see the Suggested Tools at the bottom of page) or you can do this manually.
- Make sure your environment meets the technical requirements for Joomla 4 before proceeding.
- Create a new database and new user to restore your 3.10.x site to.
- Create a testing site or build area to work in and restore the backup copy of your 3.10.x site in one of the following places:
- A subdomain.
- A subdirectory.
- A local device. Joomla has a detailed tutorial on installing XAMPP. However WAMP, MAMP and LAMP are all suitable alternatives.
- A new hosting account on a temporary domain in the root. (If you would like to change hosts in the process of migration.)
- Restoring a site on a local device. See Installing Joomla locally and Setting up your workstation for Joomla development.
- Restoring a site with a tool listed at the bottom of the page. (Read the developer documentation.)
- In your test location, update your Joomla! 3.10.x instance to the latest maintenance release.
- Make sure you have the latest database schema updated to the latest version 3.10.x version by going to Extension Manager → Database tab. If your schema is not up to date as in the following image, click the Fix button:
- Empty trash: Do you have any articles in the trash? If so, delete them (and any applicable media that may be associated with them if not in use elsewhere on the site). Articles (categories and menu items too) left in the trash can cause issues in having a migration to complete without errors.
- Test.
- Backup again.
Assess Each Extension
In your planning, you determined which third-party extensions were staying or going and how they migrate. For this portion of the Step by Step, you’ll be using two different sections of the site extensively: the Pre-Update Check in Components → Joomla! Update and Extensions → Manage → Manage. You are going to be looking at every single extension installed on your site. You will be determining if they need to be updated to the latest version or uninstalled. More details in Pre-Update Check.
- Using the Pre-Update Check in order to use the Pre-Update Check, you will need to set the Joomla! Update component to Joomla 4. To do this follow:
- Go to Components → Joomla Update It should say no updates found. If it doesn’t, update Joomla to the latest version (must be 3.10.x) and test. Then do another backup. Click on the Options button at the top right corner.
- Select Joomla Next from the drop-down for Update Channel.
- Click Save & Close
- You will then see your Installed Joomla Version, the latest Joomla! version and the URL for the update package. Joomla will show you the requirements again for Joomla 4. If it flags that you have either an incompatible system or extensions it will tell you here. Take a moment to review this page.
Notice: Do NOT update to Joomla! 4 right now. This is only to prepare your third-party extensions and get the site compatible with Joomla! 4. - Look at the Pre-Update Check and the Extension Pre-Update Check in the Pre-Update Check tab of the Joomla Update component. If any extension that isn’t in your planning is listed here, add it to your list of extensions to investigate.
- If you migrated from Joomla! 2.5 to 3.x in the past, there may be some leftover extensions that need to be cleaned up. The following are older 2.5 or 3.x extensions that need to be uninstalled before updating to Joomla 4:
- plg_content_geshi
- Bluestork Administrator Template
- Beez_20
- Beez5
- Atomic
- When it comes to templates, uninstall all core frontend or backend templates except Protostar and Beez3 (frontend templates) and Isis or Hathor (administrator templates). NOTE: Protostar is NOT compatible with Joomla 4. Upon migration it will disappear. You'll need to have one template selected as default and you can use Protostar or Beez3. Protostar will disappear upon migration to Joomla 4.x.
- If you come across other files that need to be uninstalled, please add them to this page. This is a wiki so anyone can add to the page. Thank you in advance for your service.
- You will notice the tags for whether an extension is compatible or not. These tags generally tell a true story if they say No or Yes. If they say Missing Compatibility Tag it means that the extension developer didn’t use a tag in their extension so we don’t know if it is or isn’t compatible with Joomla 4. Talk to the developer to verify.
- Update Extensions: update any extensions that you will keep in your website. In Joomla! 3.10.x you can go to Extension Manager → Update tab and click Find Updates which will add a tooltip in the Version column, under the Manage tab, giving some compatibility information from the backend. This functionality only supports extensions that update via the Extension Manager Update tab. If you have extensions installed that do not use the Joomla extension update they need to be assessed manually as detailed below. The same goes for those extensions that have a tooltip. You will still need to check the type of package and migration path with the extension developer to verify how to upgrade/migrate.
- Investigate and Uninstall Extensions Extensions: go to Extension Manager → Manage
- Click the Button Search Tools to show the filter options
- Select Package from the Select Type drop-down.
Selecting Package first is recommended because if there is something you need to uninstall in a package, it will automatically uninstall the associated Modules, Plugins, or anything else in the package at one time. - Uninstall any Packages that are no longer needed or will not be migrating to Joomla 4.
- Repeat this process of going through the Manage tab for all Types in the drop-down: Component, File, Language, Library, Module, Plugin and Template. If the Author states Joomla! Project, then leave those extensions alone. For all others, make sure that you uninstall those not in use or not compatible with Joomla! 4.x.
NOTE! You will not be able to uninstall any template that is set as default. You will need to select a Core supported template like Beez3 or Protostar and then uninstall the template if you need to do so. Another reminder: Protostar is not compatible with Joomla 4. Upon migration it will disappear. Selecting it as default simply gets you to Joomla 4.x.
- Make a note of any versions of Packages and Components currently running that you will be keeping on your site. You can copy/paste them into a document for reference.
- For any extensions you are keeping but don't use the Extension Manager to one-click update (Extensions → Manage → Update) update all extensions to the latest versions.
- Before and as you update, note if the extensions have both 3.10.x & 4.x versions in the same package. If so, they will be fine to one-click update. If not, and 3.10 and 4.x have different packages, you need to look at them case by case. They will normally fall into one of the following scenarios:
- The extension has separate packages but upon upgrading to 4.x, they automatically detect this and still work. Make sure the developer confirms this.
- The extension has separate packages that need to be uninstalled in 3.10.x and then installed with the Joomla 4.x version once the site is migrated. An example of this might be a content plugin. It is very simple to uninstall it in 3.10.x and then install it again in 4.x.
- See Template Considerations for more specific information on templates and Converting a previous Joomla! Version template
Notes on Search (com_search)
Search (com_search) will be decoupled in Joomla 4.x. Search (com_search) will migrate to Joomla 4. After migration, you'll need to update it to the Joomla 4.x version via com_installer. It will continue to be maintained, but more the same way a third-party extension is by receiving updates via com_installer. It is recommended to use Smart Search (com_finder) going forward. Search is still available from the Joomla Extensions Directory.
Notes on Weblinks
Weblinks was decoupled back in Joomla 3.4. If it was in use on a 2.5 site, the migration process would note this and migrate the Weblinks component and data. For the migration from 3.10.x to 4.x, it will be the same. It is still available and maintained on the JED at Official Extensions.
Notes on Legacy Routing
Legacy routing will not be available in Joomla 4.x. Only Modern will be available. When you do the migration, if you are using Legacy routing, the system will automatically change them to Modern routing. You will want to run a broken link checker on your site after migrating to Joomla 4.x and before you go live.
Going to Joomla! 4.x
Once you have either updated or uninstalled your third-party extensions so that only those compatible with Joomla! 4 remain in your installation, continue with the following steps:
- Go to System → Global Configuration → Server tab and turn Error Reporting from System Default to Maximum. Make sure to Save & Close.
- Take another backup.
- Go to Components → Joomla Update. (It should say no updates found. If it doesn’t, update Joomla to the latest version and test. Then do another backup.) Click on the Options button at the top right corner.
- Select Joomla Next from the drop-down for Update Channel.
- Save & Close.
- You will then see your Installed Joomla Version, the Latest Joomla! version and the URL for the update package. Joomla will show you the requirements again for Joomla 4. If it flags that you have either an incompatible system or extensions it will tell you here. Take a moment to review this page.
- If the update is not showing up, go to Extension manager → Update and press Purge Cache from the toolbar. Now the update to Joomla! 4 should show up.
- Cross your fingers, and make sure you have that backup available in case.
- Click the Install the Update button.
- Make tea whilst the status bar loads to fully green. The amount of time this takes is dependent on your site, Internet connection and server speed. The process takes about two minutes. When the update is finished, you will probably be logged out of the Administrator. Sign in again. Twice.
- If all goes well, you will get to a totally new look to the backend administrator panel.
- Go to System → Maintenance → Database and click Fix if any errors show.
- In System → Install → Discover see if there are any extensions to install. (There shouldn't be any!)
- Go to the frontend of your site and see if it shows up even if it’s not the right template. If so, continue. If not, see common errors during migration.
- Take a backup.
- Install your new template or other extensions if you have them to install. Back up often.
- Configure them. Back up often.
- Run a broken link checker and fix any broken links.
- Test everything. Back up often.
- If everything works as expected, turn Error Reporting back to System Default (System → Global Configuration → Server tab). Make sure to Save & Close.
Going Live with your Joomla! 4.x Site
- When you’re ready to go live, back up your 3.10 site for the last time. Restore it in a subdirectory or subdomain if you would like to.
- Back up your Joomla! 4.x site and move or restore your Joomla! 4.x site to the root (or change nameservers if you were building on a temporary domain at a new hosting account root).
- Test again.
- IF you have made security changes to .htaccess file in the past, you may need to change a line (or lines) in it in order to update to the next version of Joomla 4. Please go to Htaccess changes after Joomla 4 to determine if you need to change your file or not.
- Remove the Joomla! 3.10 site from the server within a couple of days unless you have edited your robots.txt file to block the search engine spiders.
- Remove all development sites you have been working with or keep them up-to-date if they are running a current version in order to ward off hack attempts on your server.
If you had data change on the 3.10 site while you were migrating to 4.x, you will want to get that data moved over to the 4.x site before going live. You can do this manually (make sure you keep the same user IDs - go in order) or by using a third party extension.
Suggested Tools
- Akeeba Backup is very popular for backup and restore.
- More backup tools.
Migration Basics
Terminology
Joomla! documents use a variety of terms to mean change from an older version to a newer version:
- Migration or mini-migration is a term usually applied to a change from an older to a newer Major version, sometimes through several interim Major versions.
- Upgrade is a term usually applied to a change from one recent version to the next version in a sequence of Minor versions.
- Update is a term usually used for the Upgrade process using the Joomla Update component. It is the word seen in the Administrator interface in Joomla! 3, 4 and 5. From now on the term Update will be used in this article.
It is also worth knowing that Joomla follows the Semantic Versioning standard. In brief, given a version number MAJOR.MINOR.PATCH, such as 5.1.0:
- The MAJOR version allows for backward compatibility breaks.
- The MINOR version allows for additional functionality in a backward compatible manner within the Major version.
- The PATCH version allows for backward compatible bug fixes.
There may be additional suffixes such alpha, beta or rc, but not in stable releases intended for production sites.
Reasons to Update
The reasons to update are many and varied:
- Security Although Joomla! is recognised as a very secure CMS, occasional vulnerabilities are discovered and fixed in Minor or Patch releases.
- Hosting changes Joomla uses the PHP scripting language and a database server such as MySQL, MariaDB or PostGres. They progress through changes and hosting services need to keep up to date. So you may find that an older version of Joomla no longer works or fails to work if you move hosting service.
- Design changes You may wish to make your site look better, work better with mobile devices and score more highly with search engines. You might have to meet legal Accessibility rquirements.
- Functionality You may wish to use a Joomla extension that provides some feature not provided by core Joomla extensions. Choices may be limited by your current Major version.
Backup before Update
This is really important! Even if you have accomplished several interim updates it is possible that something may go wrong during the update process. This may leave your site broken. The standard advice offered in the Forums is revert to your last backup, find out why the backup failed, fix it and then try again.
Akeeba Backup is a free tool obtainable from the Joomla Extensions Directory (JED) to which you have direct access via System / Install Extensions / Install from Web. It only takes a minute or two to download and install. It analyses your system to configure a profile using a Configuration Wizard. It then makes a backup which you can download for safe-keeping.
Self Assessment
Before performing a Major or Minor version update you need to assess your system and your existing third party extensions for compatibility with the Joomla target version. It is a good idea to make a list of the third party extensions you have installed. In Joomla 4 and 5 the System / Extensions / Manage list has a filter to select None-core Extensions. This is not present in Joomla 3.
You could also use the Forum Post Assistant. This is a tool intended to analyse a site and make a report suitable for posting on the Joomla Forums to help the Forum experts diagnose problems with your site. However, it has a private user interface that tells you all about your site. Its extensions lists (Components, etc.) indicate which are 3rd Party.
The problems that arise during updates are usually associated with third party extensions not being code compatible with your target Joomla version. You should check each extension for compatibility and uninstall any that are known to be incompatible. You may be able to install compatible versions later.
You should set one of the default Site templates as your default template:
- Joomla! 1.5 default templates are Rhuk_milkyway, JA Purity, Beez.
- Joomla! 2.5 default templates are Atomic, Beez3, and Beez25.
- Joomla! 3 default templates are Protostar and Beez3.
- Joomla! 4 default template is Cassiopeia only.
Local Testing
If at all possible, it is best to set up a local testing environment on your laptop or home workstation to test your update procedure. You can use the backup of your online site to populate your test site. Your home site must be able to run your copy of your live site and have adequate PHP and Database specifications to run the updated site. There is a separate article describing how to set up a home testing environment.
-->Version Update
Introduction
Remember: Always back up your site before updating.
The recommended way to update installations of Joomla! is to use the Joomla Update Component.
A standard installation of Joomla 4 and later includes a helpful notifications panel on the Home Dashboard after login. You can see at a glance if an update is available and the version number.
The Update message that appears in the Notifications panel depends on the Update Chennel set in the Joomla Update: Options page and the current Minor version. With Update Channel set to Default, updates within the current Major version are notified. With the Parameter set to Joomla Next you may update to the latest current version and then select the Check for Updates button to see if the next Major version is available.
Although Joomla will notify you when an update is available, it requires you to carry out the update. It is a simple process that should be carried out at the earliest opportunity to keep the site up to date.
Accessing the Update Component
If the notifications panel is displayed in the Home Dashboard, select the x.y.z Available - Update Now! button go to the Update Component.
Alternatively, to access the Update Component from the Administrator menu, select System to go via the System Dashboard.
The System Dashboard has an Update Panel which includes a Joomla link that will show the available update version number. Select the Joomla link to go to the Update Component.
Carrying out the Update
Joomla! 4 and 5 provide a Pre-Update Check for Updates to Minor Versions. This view of the Joomla Update component shows technical specifications of the server the site is on and core and third-party extensions that use the Update Server in a list form.
Note: The Pre-Update Check screen is only displayed for major and minor version (e.g. 4 to 5, or 5.2 to 5.3). It is not displayed for patches (e.g. 5.3.1 to 5.3.2).
Pay careful attention to check results and take action to rectify any issues highlighted before updating. You may need to update, disable or uninstall incompatible extensions before updating Joomla.
It is not uncommon to see warnings for Recommended Settings as these are often server specific and hosting related. It is likely they existed when you installed Joomla and most likely won't prevent the update from completing.
Note the reminder that you are strongly advised to take a backup if you haven't already!
There is a link below the update button. In most cases you can ignore this link. It provides an option to manually upload the update files if your server is behind a firewall or otherwise unable to contact the Joomla update servers.
When you have reviewed the Pre-Update Check and are happy, select Update.
Confirming the Update
Click the checkbox to confirm you have made a backup and checked extensions are compatible then click the Start Update.
Update Progress
Once the update starts a progress bar will appear as the Joomla files are updated.
Completion
When the progress bar reaches 100% a system message will confirm your site has been updated and the version number. The version number will also update in the top toolbar, next to the site name.
Click the Back button and you will be returned to the Joomla Update Component where it is possible to check for updates again.
Post Update Checks
Once the update is complete you should carry out some checks to make sure everything went as expected, that no errors are present and that there have been no changes that require further action.
Frontend Check
Go to the front end of the website and check it is working and displaying as it did prior to the update. Use the Shift + Reload combination to force your browser to reload any changes to stylesheets and scripts.
System Checks
From the sidebar menu select System to be taken to the System Dashboard. This gives you an overview of the current status of your Joomla site.
In this example we can see that since the update we have two items that require attention. They are marked with a label that includes a number. The number relates to how many items require attention. Clicking on each one will allow you to fix them.
Note The System Dashboard makes a check each time the page is loaded. Bear in mind that browser caching settings could affect this. It's good practice to clear the browsers cache when checking using Shift + Reload.
Database Check
Navigate to System → Maintenance → Database. If your database is up to date, you should see a screen similar to the one below:
If your database is not up to date, you will see a screen listing the problems found, similar to the one below:
In this case, select the problem extension Name and then the Update Structure button in the Toolbar. Joomla will update your database to correct the issues listed and then it will re-display the screen. If the fix was successful, the display will indicate that the database is up to date.
Note: If any errors still exist make sure all the database tables are checked in.
System Discover
In some cases, when you update to a new Joomla version, new core extensions are added. If there were problems with the database update, these extensions may not have been correctly installed. To check this, navigate to System → Discover. Then select the Discover icon in the toolbar. The screen should show as follows:
If so, you know that any new extensions added during the update were correctly installed in the database.
If there are uninstalled extensions, they will show similar to the following screen:
In this case, check the boxes and click on the Install icon in the toolbar. Joomla will install the extension(s) and then display the screen showing no extensions discovered. At this point, the new extensions have been installed in the database.
Troubleshooting
If you have any questions, problems or errors before, during or after the update, please ask them on the Migrating and Upgrading to Joomla! 5.x Forum.
If you have problems or errors during the update process, here are some tips.
- Clearing your browser cache. There may have been changes to the CSS or Javascript that will need to be reloaded by your Web browser after an update.
- If any database error messages show after the update, be sure to check the System → Maintenance panel → Database link. In some cases, if a database error occurs it will prevent all of the database updates from running. In this case, you can run them from the Database link and then use the System → Install → Discover method to check and install any new extensions.
- The update process creates or appends to a log file named administrator/logs/joomla_update.php which you can open with a text editor to see the steps recorded in the log. It will be show the major steps (download zip, install, run SQL statements, clean up), something like this:
2024-04-17T09:13:16+00:00 INFO 127.0.0.1 update Update started by user Jimmy (139). Old version is 5.0.3.
2024-04-17T09:13:18+00:00 INFO 127.0.0.1 update Downloading update file from ...
2024-04-17T09:13:28+00:00 INFO 127.0.0.1 update File Joomla_5.1.0-Stable-Update_Package.zip downloaded.
2024-04-17T09:13:28+00:00 INFO 127.0.0.1 update Starting installation of new version.
2024-04-17T09:13:40+00:00 INFO 127.0.0.1 update Finalising installation.
2024-04-17T09:13:40+00:00 INFO 127.0.0.1 update Start of SQL updates.
2024-04-17T09:13:40+00:00 INFO 127.0.0.1 update The current database version (schema) is 5.0.0-2023-09-11.
... Lots of individual SQL queries
2024-04-17T09:13:41+00:00 INFO 127.0.0.1 update End of SQL updates.
2024-04-17T09:13:41+00:00 INFO 127.0.0.1 update Uninstalling extensions
2024-04-17T09:13:41+00:00 INFO 127.0.0.1 update Deleting removed files and folders.
2024-04-17T09:13:44+00:00 INFO 127.0.0.1 update Cleaning up after installation.
2024-04-17T09:13:44+00:00 INFO 127.0.0.1 update Update to version 5.1.0 is complete.