Note: this article uses the term 3+ because there could be a newer release of Joomla that when this article was written. Always upgrade to the latest version of Joomla available.

The process of taking a Joomla 2.5 site to a Joomla 3+ site is considered a "mini-migration". Depending on your site and what extensions you have installed, you should be able to migrate the site to 3+ with a single click for the most part. The table structure did not change as dramatically as it did from 1.5 to 2.

If you have a large and complex 2.5 site, you may wish to use a specific migration tool provided with a Joomla Extension. Research the various extensions available for this process at:

Checklist for running the 2.5 to 3+ migration

  • Does your hosting environment meet the minimum requirements for Joomla 3+? Visit:
  • Does the template that you have installed on your 2.5 site have a matching 3+ version?
  • Do the extensions that you have installed offer a release for Joomla 3+?
  • Did someone customize your Joomla template or Joomla installation? Can you repeat these customizations?
  • Are you comfortable running the migration, installing a new template or extensions yourself or should you hire a professional?

Refer to the Joomla Docs articles on migration for a complete guideline:

Do the upgrade in a development environment

Things can go wrong with any major upgrade. You site could break or it's appearance can go all funny. It can take several hours to get the template looking good and the extensions all in order. A broken is not something you want your visitors to see.

It is best to do the upgrade to 3+ on a local computer or in a subdirectory on your hosting account. You will need to copy the site's folders and files and database to the new location. If you are doing it on your hosting server, be sure to create a duplicate database for the new site. If developing on your local computer, you need to be running XAMPP or WAMP. This process also involves editing the configuration.php to point to the new database.

Backup your current 2.5 site as it is right now

Before starting the migration process, backup your current 2.5 site's files and database. Use Akeeba backup extension if you are more comfortable using this method.

Copy your site and database to a development environment

Whether you are doing the upgrade on a local computer with XAMPP, WAMP or LAMP installed or you are doing the upgrade in a subdirectory on the host server, you need to place a copy of all the sites files and folders in the new location.

You also need to create a new, separate database then import the .sql file from the existing database. Once this is set up, you need to edit the configuration.php file on the root of the copied Joomla files and edit it to point to this duplicate database. Be sure to enter the new Database user name and password if necessary. If you are doing the upgrade on your host server, you must do it with a new copy of the database. The two sites must have be separate databases.

Upgrade your current Joomla 2.5 site to the last 2.5.28

If your current site is not at version 2.5.28, you should upgrade it to that version before starting the migration process to 3+. 

Before running any upgrade, you should:

  • turn off any caching
  • clear the existing cache
  • turn on error reporting and set it to the maximum
  • disable the Remember Me plugin in Plugin Manager

If the upgrade returns a blank white screen, the errors will be displayed. These error can give you a clue as to what went wrong. 

You can go to the Components dropdown and select Joomla! Update. If you are not at 2.2.58, it should let you upgrade from there. 

If it won't let you or it doesn't work, you can get the download for this update at:

Upload this file through Extension Manager.

Once the 2.5.28 version has been installed, check that the database is up to date in Extension Manager -> Database tab. Click on the Fix button if it tells you that it is not up to date.

Open up the upgraded site in a browser. If you find that things don't look quite right it could be that someone made custom changes to the core files. The Joomla core files are replaced with any upgrade. It is best to use template overrides that are placed into the html folder of your template. This way they stay in place, are not overwritten and you can see at least which files you are dealing with.

Customization of the template files can also be lost with upgrading. It depends on if your template is included with the Joomla installation files. In the future, you should keep track of what customizations are made to the template so that you can replace or repeat them when you upgrade. At this point, you may wish to hold off on replacing any customization until you have installed the Joomla 3 version, no sense repeating these steps.

Once this upgrade is successful, backup your site's folders and files and database again.

Assess the extensions in your 2.5 site

Go into Extension Manager -> Extensions and click on Manage. You will see a list of all the current extensions on your site.

Some of these extensions come with Joomla, others may be 3rd party extensions. Most of the extensions included with Joomla have Joomla! Project as the authorthough a few will not.

Look through the list and check to see if the ones you have installed have matching versions for 3+. If they don't, research any replacement extensions that have the same functionality. The replacements will likely not be able to use the data from the old extension, so some migration will be necessary.

Uninstall any extensions from your development site that do not are not necessary for the functionality of your site or that don't have a release for Joomla 3+. Be sure that you uninstall the entire package, including any plugins. You need to realize that the upgrade may hang if it is looking for any plugins that don't exist.

Joomla Docs suggests that you upgrade your extensions prior to upgrading the Joomla installation. You should really deal with this with each extension individually. Some should be upgraded prior to the migration to 3, some need to wait until 3 is in place to upgrade. See the documentation for the extension.

Run the upgrade from 2.5.28 to 3+

Once you have done the upgrade to 2.5.28 and taken care of any extensions that you have installed, you should be able to update to latest version of Joomla 3+ from Components -> Joomla Update.

If the screen isn't showing you that  the 3+ version is available, Select Short Term Support in the dropdown.

Common problems with upgrading from Joomla 2.5 to 3+

The upgrade may stall while you are running it. This can be due to several factors:

  • the database is not updated
  • there are files or folders with incorrect permissions
  • your hosting environment does not meet the minimum requirements for Joomla 3+

Once your run the upgrade, you may come to a blank white screen. Hopefully you were smart and turned on error reporting before you ran the upgrade. Look at these error messages. Often it is telling you that it cannot find some file. This may be because some plugin needs to be disabled. You can either restore the 2.5.28 installation from the backup, or disable the plugin using phpMyAdmin.

Check with if you have specific issues with migrating. Before posting a question, research and see if anyone else has already dealt with this particular issue.