Over the last couple of years, this site has been running on Joomla 2.5. However, official support for Joomla 2.5 ended on December 31st, 2014. On a rainy afternoon, I decided to upgrade to Joomla 3. Here’s how it worked for me – if you’re in the same situation, this tutorial will help you to upgrade your own site from Joomla 2.5 to Joomla 3.3 or higher.

Step 1: check if your web host supports Joomla 3

First, check if your web hosting services are compatible with Joomla 3.3. In your 2.5 site, you can see the current versions of these services. Navigate to Site > System Information.


The requirements to install Joomla 3.3 are PHP 5.4 (on the System Information page, you can check the current version your web host supports under PHP Version) and MySQL 5.1 (on the System Information page you can see the version your web host supports under Database Version). See also http://www.joomla.org/technical-requirements.html.

Also check if the extensions and template you use, are compatible with Joomla 3. The best way to find this out is by checking the site of the extension developers. You’ll need to replace the old extensions manually later in the process.

Step 2: create a backup of the existing site

Upgrading the Joomla 2.5 software itself to Joomla 3.x is a one-click process. However, upgrading extensions and templates used for your old site isn't automated. How much effort this takes, depends on what extensions and templates you're using. Moreover, it's best to first backup your site and perform the upgrade on the backup copy. This is what I've done first. This way, you can install a copy of your site (the backup) on another, temporary location and perform the upgrade. Only after the upgrade has succeeded and you’ve tweaked the upgraded site, you replace the old site by the new one.

To backup the site, I use Akeeba Backup. It’s a very popular (free) backup tool. It allows you to create a backup and also to reinstall that version of the site on a different location.

In the next few steps, I assume you’ve got Akeeba already installed. To find out more about Akeeba, see the Joomla Beginner’s Guide Second Edition, Creating a Backup with Akeeba Backup section in Appendix A, Keeping the Site Secure. To follow along, you also need te know how to upload files to your web hosting space using FTP software or the Control Panel of your web host. This also is covered in more detail in the Joomla 3 Beginner’s Guide Second Edition.

· Navigate to Components > Akeeba Backup and hit the Backup Now button.

· After the backup has completed, click Manage Backups:



· Click the Part 00 button (shown below) to download the Akeeba backup file to your computer.




Install a copy of your site on a temporary location

The next thing to do is create a temporary location to re-install the backup as a copy of your current site. For example, you can create a subfolder or a subdomain on your web hosting space, using the Control Panel provided by your web hosting company. In this case, I created a subdomain j3.joomm.net.

  • Copy the Akeeba backup file you downloaded to your computer to the root folder of the subdomain or subdirectory you just created. This can be done either with FTP software or using the File Manager of the control panel of your webhost (as shown in the screenshot below):


  • The Akeeba backup file is a compressed file, containing all files needed to re-install the site. To be able to extract the backup files on the web server, you’ll need another tool provided by Akeeba: Kickstart. Download the Akeeba Kickstart tool from https://www.akeebabackup.com/products/akeeba-kickstart.html.
  • Extract the downloaded Kickstart zip file on your computer. Upload all extracted files to the folder on your web hosting space where you copied the Akeeba backup file.

Create an empty database

You’ll be installing a second Joomla site on your web hosting space. This means a new, empty MySQL database has to be available. Create this database just like you’ve created the database for your Joomla 2.5 site. In my case, the web hosting company provides Control Panel – which is a very common situation. In this Control Panel, I could add a new database using the Databases button. I also created a new database user, allowed to manage the database. Your web hosting company should provide a similar functionality or will be able to provide you with the procedure involved in creating a database.

After the database has been created, make a note of the database details: it’s name, the host name, the user name and the user password.

Re-installing the copy of your site

You’ve now got everyting ready to create a copy of your site: the backup file and Akeeba Kickstart have been uploaded to the temporary site location, an empty database is ready for use.

  • Navigate to the URL of the temporary site location, followed by kickstart.php. In my example, this was http://j3.joomm.net/kickstart.php. This will run the Akeeba Kickstart tool.

· You’ll be shown the first Akeeba Screen (‘Things you should know about Akeeba Kickstart’). Close the message to continue. Click Start to extract the files from the backup:


Akeeba Kickstart will start extracting all backup files to the server. This can take several minutes.

  • After all files from the have been unpacked, click Run the installer:


  • The Akeeba Installer will start. Click Next in the top left corner of the first screen:


  • In the next screen, Restoration of site's main database, carefully enter the details of the new, empty database you created.


  • Click Next to restore the database. After completion, click Next step to continue:


  • On the next screen, Site Setup, you can leave all site details (such as the site name) unchanged. Click Next (in the top right corner) again to finish the installation.
  • On the ‘Finished’ screen, click the button in the middle of the page to Remove the installlaton directory:


You’re almost done. Click Visit your site’s front end to see the results. In another browser tab, the Akeeba Kickstart screen is still open. Navigate to that tab and click Clean Up to automatically delete all files belonging to the Kickstart tool:



Step 3: Updating Joomla

You can use the built-in Update component of Joomla 2.5 to upgrade to version 3.0 or higher. However, there are a few things that you have to keep in mind: ‹

  • The template system of Joomla 3.x has changed, which means you can't just use your old Joomla 2.5 template in Joomla 3.x. Often, it’s a good idea to use the switch to Joomla 3.x as an occasion to change the looks of your website and use a new 3.x-ready template. ‹
  • Most third-party extensions developed for Joomla 2.5 will have to be converted by their developers to make them Joomla 3.x compatible. If you need to use an extension that's not yet ready for Joomla 3.x, you may need to look for an up-todate extension that offers similar functionality.
  • By default, in Joomla 2.5 you'll only receive updates for Joomla 2.5 (Version 2.5.1 and so on). To enable automatic updating from Joomla 2.5 to Joomla 3.x, go to Components > Joomla! Update. Click on Options.
  • Change the Update Server to Short Term Support:


  • Click Save & Close. On the Joomla! Update screen, you’ll now see a notice that an update is available. Click on Install the update. The progress of the update process is shown. This can take a while:


image014.pngAfter completion, the appearance of the backend will change and Joomla will notify you what the current Joomla version number of your site is:

 Step 4: updating extensions and templates

Check what the website looks like on the front end. Chances are that the current template doesn’t (fully) support Joomla 3. In that case, it’s a good idea to go to the Template Manager and switch to the default template of Joomla 3, Protostar. This way, you’ll have a template that is certain to function without any problem. After that, you can decide whether you want to keep this template or install another one. Below you can see what my site looked like after I activated the Protostar template. The main elements are in place, but all modules in the right column aren't shown any more. This is okay for now: I can see my site works and that all contents are okay. The next step for me was to find a new Joomla 3 compatible template and assign modules to the positions available in that template. 


Removing old templates and extensions

  • It’s best to remove old templates that you no longer need. To do this, go to Extensions > Extension Manager and click Manage in the left hand menu. Under Filter, select Template.
  • Now select the templates you no longer need and click the Uninstall button.




  • It’s very important to switch off all extensions in your new site that were made for Joomla 2.5. As long as they are still installed, they can cause all sorts of problems (such as white screens on you Joomla site; see below). Find the existing extensions (through Module Manager and Plugin Manager) and disable them. In my case, I disabled all extensions and uninstalled them using Extensions > Extension Manager > Manage > Uninstall.
  • ·Install up-to-date replacements for the extensions you need.

After you’ve replaced the template and the extensions, you can re-assign modules to the positions available in the new template (just follow the general procedure for switching templates and assigning module positions; see Chapter 9 in the Joomla 3 Beginner’s Guide Second Edition).

Finally check your if your site settings are okay. You may want to tweak global settings under Global Configuration (such as the settings for pretty URLs and the Cache settings).

What if you’re getting a white screen in Joomla 3?

After updating my site, everything went fine until I tried to access my articles in the backend of the site. Suddenly, Joomla displayed a white screen, without any error message. To find out what was going on, I switched on error reporting:

  • Navigate to System > Global configuration > Server. Under Error reporting, select Maximum.
  • Navigate back to the backend pages that gave a white screen. You should now see an error message at the top of the screen. This will indicate what Joomla file is causing the error. In my situation, this pointed to a plugin file that I had forgotten to disable. After disabling and removing the plugin, all was fine.

If the error message doesn’t make sense to you, just google the exact phrase. Other Joomla users may have encounterd the same error message and have come up with a solution.

Step 5: replace the old site with the new one

Now that your backup copy of the site is working as intended, you can replace your “old” site by the new one. Here’s how I did it:

  • First, create a backup of the new site using Akeeba Backup. The procedure is exactly the same as described in the first part of this tutorial, when you created a backup of your existing site.
  • Next, I created an index.html file saying the site is under construction. This will be up while the site is renewed behind the scenes. The web server is set up to always show an index.html file, even if there’s an index.php file present (as used by Joomla). So even if there’s still a Joomla 2.5 powered site present, web visitors will be shown the message in the index.html file.

The final steps are erasing the current site and replacing it by the backup of the new site:

  • Navigate to your current site using FTP and delete all files on the site, except for the index.html file.
  • Upload the backup of the new site to the new location. Also upload the Akeeba Kickstart files to the new location
  • Run Akeeba Kickstart. In my case, the URL I had to enter to do this was http://joomm.net/kickstart.php. This will run the Akeeba file extractor.
  • After all files have been extracted, click Run the installer. The procedure is the same as described under Step 2. On the database page, enter the database information of the database for the “old” site. Akeeba will restore the database, you can check the site settings, remove the installation directory and visit the site’s front end. The new site is ready!

Replacing Joomla 2.5 by Joomla 3 is a one-click procedure – but as you’ve seen, there’s a lot more involved. It’s very important to first backup the site and perform the upgrade on a copy of the site on a temporary location. This way, your current site will only be offline for a few minutes: when you delete the old site files and restore the backup of the new, Joomla 3 powered version of the site that.