Tom Hutchison/Step by Step example

From Joomla! Documentation

< User:Tom Hutchison

The following are step by step instructions to migrate your 2.5.x site to Joomla 3.x. While there are hundreds of different scenarios, this will give you the basic procedure to follow. Very complex migrations will likely be as a result of third-party extensions. You are encouraged to contact the developers of third-party extensions for their suggested path to migrate their extensions.


The migration from Joomla 2.5 to 3.x is considered a mini-migration. This is because the Joomla core extensions will upgrade with a “one-click” upgrade via the backend administrator side of Joomla. Many third-party extensions are a one-click upgrade too. You need to look at each one and determine what path the extension needs to follow to get from 2.5 to 3.x.

Joomla Core Extensions:

  • Categories
  • Articles
  • Menus
  • Modules (core modules - not third-party)
  • Banners
  • Contacts
  • Messaging
  • Newsfeeds
  • Redirect
  • Search
  • Smart Search
  • Weblinks

Step by Step

  1. Take a backup of your live 2.5 site. You can use Akeeba Backup which will backup your site files and database tables or you can do this manually
  2. Make sure your environment meets the technical requirements for Joomla 3 before proceeding
  3. Create a new database and new user to restore your 2.5 site to.
  4. Create a testing site or build area to work in and restore the back up copy of your 2.5 site in one of the following places:
    • A subdomain
    • A subdirectory
    • A local device via WAMP, MAMP, LAMP XAMPP [ links to local device builds here ]
    • A new hosting account on a temporary domain in the root
      • Restoring a site on a local device [ WILL SOMEONE PLEASE FIND THESE AND LINK THEM. THEY NEED TO BE UPDATED ].
      • Restoring a site with Akeeba Backup (read the developer documentation or videos for how to restore a backup of an Akeeba Backup file)
  5. In your test location, update your Joomla 2.5 instance to the latest version of Joomla.
  6. Test.
  7. Backup again.
  8. Go to Extension Manager  Manage tab
  9. Click the drop-down for Type.
  10. Select Package from the 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.

  11. Uninstall any Packages that are no longer needed or will not be migrating to Joomla 3.
  12. Make a note of any versions of Packages currently running that you will be keeping on your site. You can use the Third-Party Extension Inventory Worksheet (LINK TO WORKSHEET) or just copy/paste them into a document for reference.
  13. Repeat this process of going through the Manage tab for all Types in the drop-down: Component, File, Language, Library, Module, Template. If the Author states Joomla! Project, then you’re golden. For all others, make sure that you uninstall those not in use or not compatible with Joomla 3.x.

    You will not be able to uninstall a Template that is set as default. You will need to select a Core supported template like Beez or Atomic and then uninstall the template if you need to do so.

  14. Update all extensions to the latest versions.
  15. Before and as you update, note if the extensions have both 2.5 & 3.x versions in the same package. If so, you’re good to go. If not, and 2.5 and 3.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 3.x, they automatically detect this and still work. Make sure the developer confirms this.
  16. The extension has separate packages that need to be uninstalled in 2.5 and then installed with the Joomla 3 version once the site is migrated. An example of this might be a content plugin. No big deal to uninstall it in 2.5 and then install it again in 3.
  17. See Template Considerations for more specific information on templates.

    Note on Core Supported Extensions:
    If you are using a Core Supported Extension (Banners, Contacts, Messaging, Newsfeeds, Redirect, Search, Smart Search, or Weblinks) in Joomla 2.5 and it has been decoupled in Joomla 3, Joomla will detect their use during the upgrade and install those Core Supported Extensions automatically. (THIS IS MY UNDERSTANDING FROM DAVID H. & MICHAEL B.)
    Once you have either updated or uninstalled your third-party extensions so that only those compatible with Joomla 3 are remaining in your installation continue with the following steps

  18. Go to System -> Global Configuration -> Server tab and turn Error Reporting from System Default to Maximum. (SCREEN CAP?)
  19. Go to Extensions -> Plugin Manager and enter Remember Me into the Filter and press enter.
  20. Disable the Remember Me plugin by clicking the green check mark and making it a red circle. (SCREEN CAP?)
  21. Take another backup
  22. Install ACL Manager ( and run the Asset fixes for Missing, Orphaned, and Asset Fixes. This will take one minute with ACL Manager or your can do this manually (Fixing_the_assets_table ) (SCREEN CAP?)
  23. 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.
  24. Select Short Term Support (Current text - this may be different when you get there) from the drop-down for Update server. (SCREEN CAP?)
  25. Click Save & Close.
  26. You will then see your Installed Joomla Version, the Latest Joomla! verion and the URL for the update package. (SCREEN CAP)
  27. Cross your fingers, make sure you turned off remember me and that you have a backup from just before this point.
  28. Click the Install the update button.
  29. Watch the spinning circle go round and round and feel the anxiety building. No just kidding. The time the wheel spins is dependent on your site, internet connection and server speed (I think).
  30. If all goes well, you will get to a totally new look to the backend administrator panel (NEED SCREEN CAPTURE).
  31. Click the Purge button given.
  32. Go to Extensions -> Extension Manager -> Database and click Fix
  33. From the Extension Manager go to Discover and see if there are any extensions to install
  34. Run ACL Manager again and fix the assets or do it manually. See #18 above.
  35. Enable Remember Me from the Plugin Manager.
  36. 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 (NEED SECTION /PAGE?)
  37. Take a backup.
  38. Go to Content -> Article Manager -> Options button -> Editing Layout tab and set the Save History to Yes.
  39. Install your new template or other extensions if you have them to install. Back up often.
  40. Configure them. Back up often.
  41. Test everything. Back up often.
  42. When you’re ready to go live with it, back up your 2.5 site for a last time. Restore it in a subdirectory or subdomain if you would like to.
  43. Back up your Joomla 3.x site and move or restore your Joomla! 3.x site to the root or change nameservers if you were building on a temp domain at a new hosting account root.
  44. Test again.
  45. Remove 2.5 site from server within a couple of days.

If you had data change on the 2.5 site while you were migrating to 3.x you will want to get that data moved over to the 3.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 transfer tool/third-party extension (