Advice on upgrading to Joomla 4.0 Topic is solved

Need help upgrading your Joomla! website or converting to Joomla! 4.x?

Moderator: General Support Moderators

Forum rules
Forum Rules
Absolute Beginner's Guide to Joomla! <-- please read before posting, this means YOU.
Forum Post Assistant - If you are serious about wanting help, you will use this tool to help you post.
Windows Defender SmartScreen Issues <-- please read this if using Windows 10.
User avatar
Joomla! Explorer
Joomla! Explorer
Posts: 260
Joined: Sat Dec 08, 2007 8:23 pm

Upgrading Your Website to Joomla 4.0

Post by LukeDouglas » Sun Oct 10, 2021 10:12 pm

Upgrading Your Website to Joomla 4.0
by Luke Douglas, Webbering
With contributions by Per Yngve Berg & sozzled

This is a guide for people needing to upgrade their websites to Joomla 4.0. Any upgrade for a 'major' update shouldn't be idly done. It is a process, not a simple update. I will probably wait until January 2022 before attempting any upgrades to Joomla 4 for my client’s website but that is my own ‘cautious’ approach to major updates. This will give time for core problems to be fixed as well as 3rd party developers to make their extensions compatible with Joomla 4. However, I will be upgrading some of my own personal websites to Joomla 4 between now and January 2022. This is to find any issues that may occur and what solutions are available to get a website that functions properly as well as to become more familiar with the Joomla 4 changes.

My Experience
I have a dedicated HostGator server and only my clients’ websites are on the server. About 80% of them are Joomla websites and all are updated through Joomla 3.10.X under PHP 7.4. I've used Joomla since 2005 after it branched off from Mambo. I've gone through hundreds of migrations to Joomla v1.5 to v2.0 to v2.5 to v3.0. Not all have gone smoothly! 😊

If you find any errors in this document or suggestions to improve clarity and accuracy, send me a Private Message from my profile, memberlist.php?mode=viewprofile&u=163417.

Upgrade Process
The process will include the following steps:

Prepare for creating a development website. You do NOT want to update to Joomla 4 on a live site!
  1. If your site can be put offline, Change the Global Configuration > Site > Site Offline to 'Yes'. This will prevent any changes to the website from frontend users while you are working on the migration to Joomla 4.
  2. If your site can’t be put offline and must stay live, then here are your options:
    1. If no changes are made via the frontend but through the admin panel, then here are your options:
      1. Notify everyone with access to the backend admin panel that they should NOT make any changes after the date of beginning the update process as those changes will be lost when the update website goes live.
      2. Disable all users with access to the backend admin panel by clicking the Enable button on their User Account. Notify everyone that you are disabling their access until the update process is completed. You would NOT disable access for the user who will be doing the update. 😊
    2. If users are modifying content, either through front-end editing, e-Commerce shopping carts, or community interaction functionality, you might want to do this during a low period of usage which you can view analytics or logs to determine the best time. Be aware, you’ll have to manually update the tables for changes made via the live frontend after you create the development website that is upgraded to Joomla 4. This is NOT for the faint of heart as it will require migrating ‘only’ the content that has changed since you created the development website. There are Joomla extensions that may provide this functionality without having to delve into physically exporting and importing records from various tables.
Steps to create the development website:
  1. Create a subfolder 'joomla4' in your Joomla root folder, usually “public_html”. Note: I use ‘joomla4’ in all folder references in this guide. If you use a different name, you’ll have to remember to use your name instead of ‘joomla4’.
  2. COPY (not MOVE) all files/folders from your root into the newly created folder 'joomla4'.
  3. Export your Joomla 3 database into a SQL file.
  4. Create a new Joomla 4 database. FYI, you might want to change the database name as it will have unnecessary text from the import. I would suggest that you include “j4” or something to identify it as the Joomla 4 database somewhere in the name. My format example: “USERNAME_jml4_taru9uveChew2Uje”.
  5. Create a new user and assign to the Joomla 4 database with full privileges
  6. Go to your 'joomla4' folder and edit the configuration.php file.
  7. Change the $db (database), $user, and $password fields to the new Joomla 4 database settings, then save your file. Note: Ensure the values are within the ‘’ quotation marks.
  8. From a browser, open the 'joomla4' website administrator page and login.
  9. Change the Global Configuration > Site > Use URL Rewriting to 'No' [FYI, within a subfolder, this function does not work well at all in my experience]
  10. Save & Close the Global Configuration settings
  11. From a browser, open the 'joomla4' website front page, i.e. public_html/joomla4/ and ensure everything looks like the live website except for the URL.
    1. If the front-page does not load, you’ll have to recheck the database, user, and password fields as this is likely the problem. If they are correct, use developer tools to diagnose the issue. When fixed, come back to this section.
    2. If the front-page loads properly and navigation works, then you have a mirrored website of your live website with its own database so anything done in the 'joomla4' website will not impact your live website.
    3. Open the ‘joomla4’ administrator login page, ie: public_html/joomla4/administrator/index.php
      1. If the administrator login page doesn’t load but front page does, diagnose with developer tools to determine why it’s not loading, then fix it so it loads.
      2. If the administrator login page loads, then you are ready to continue the update process.
  1. Ensure your webhosting environment meets the Joomla 4 technical requirements.
  2. At a bare minimum, use PHP 7.4 but PHP 8.0 is recommended.
  3. Ensure your template is compatible with Joomla 4.0.x.
    1. If it is not compatible, change to a template that is J3.10.x & J4.0.x compatible, then change the styling to match what is on the live site.
    2. If it is compatible, ensure you have updated to the most recent version
  4. Update all add-on's to most recent versions (components/modules/plugins)
  5. Update to Joomla 3.10.x & test the development site to ensure it’s working.
    1. If it doesn’t work, I suspect the issue may be an add-on that is not compatible with 3.10.x. you’ll have to diagnose with developer tools to determine why it’s not loading, then fix it so it loads.
    2. If it does work, you can continue the Pre-check process
  6. Go to the Joomla Update component and review the Pre-Update Check for Joomla 4.0.x
  7. Ensure Required PHP & Database Settings are all 'Yes'
  8. Ensure Recommended PHP Settings are green, hopefully without no orange warnings.
    1. If any items are orange, it doesn’t necessarily mean that the update won’t work but it’s best if everything matches the recommended settings.
  9. Proceed to the next section
Check Extensions – Red, Orange, or Green:

Before proceeding, determine if any add-ons are not needed and uninstall them. Run a new Pre-Update Check for Joomla 4.0.X and it will give you three sections. Note: Click [More Detail] for versions
  1. Red – Updated Information Unavailable.
    1. Extension does not offer a compatible version for the selected target version of Joomla. This could mean the extension does not use the Joomla update system or the developer has not provided compatibility information for this Joomla version yet.
  2. Orange – Update Required.
    1. Please update these extensions before updating Joomla. Please take extra care if this updated version of the extension is not also listed as compatible with your current version of Joomla.
  3. Green – No Update Required.
    1. The extension developer states that the currently installed version is compatible.
Update Extensions under Red and/or Orange
Before proceeding, determine if any add-ons are not needed and uninstall them.
  1. Run a new Pre-Update Check for Joomla 4.0.x and it will give you three sections
  2. Optional: Created a MS Excel or Google Sheet to track Red/Orange extensions that are not shown as compatible. Here is what I am using: Google Spreadsheet
  3. Check 3rd party developers’ websites for ‘Unknown’ / ‘Incompatible’ extensions to determine if they have a version of their extension that is compatible with Joomla 4.0
    1. If they do, update the extension to the compatible version
    2. If they don't, confirm if they will be updating their extension to be compatible with Joomla 4.0.
      1. If they will be developing a compatible version, get a TBA date when it will be available. Note the date so you can get the compatible version and install.
      2. If they will not be updating to a compatible version, find/install a compatible alternative or create a workaround and uninstall the non-compatible version.
    3. Once all extensions have been updated, replaced, or uninstalled for each website, check to ensure website is functioning properly.
    4. After going through all extensions, rerun the Pre-Update Check for Joomla 4.0.x.
    5. Rinse and repeat until there are no Red conflicts that will might impede the Joomla 4.0.x upgrade! Remember, Orange warnings are simple warnings of ‘potential’ incompatibility.
    6. IMPORTANT! Backup the database and files!!! This is your fallback to Joomla 3.10.0 in the event the upgrade to Joomla 4.0.x fails.

      Upgrade to Joomla 4.0.x
      1. On the Joomla Update, click the Update tab
      2. Click the checkbox if there are any potential plugin problems to proceed the upgrade
      3. Click the Install the Update
      4. After updating, check to ensure the website is functioning properly.
        1. If the site works properly with at least PHP 7.4 and Joomla 4.0, you're all set! Give yourself a cookie!ss
        2. If it isn’t, determine extension/extensions causing issues and check for updated versions
          1. In the Global Configuration > Server tab, set the Error Reporting to Development
          2. On the front page, navigate to the problem page and record what errors are shown
          3. Research and make necessary changes to fix the problem.
            1. If the website functions properly after your fixes, you're all set! Give yourself a cookie!
            2. If the website still does not function properly, note the errors for research. Then, you have a decision to make.
              1. Stay with Joomla 4.0 and work to fix the problems
              2. Restore your last Joomla 3.10.0 backup (shown above IMPORTANT!). You can research to determine what you need to do at this point. Regretfully, I can't anticipate all problems.
      Note: If the updated site is working, Be sure to reset your Global Settings > Site > SEO Settings > Use URL Rewriting to ‘Yes’ if you want SEO friendly URL’s.

      More information on Joomla! 4


Return to “Migrating and Upgrading to Joomla! 4.x”