Updating from an existing version

From Joomla! Documentation

Revision as of 17:10, 28 January 2012 by Dextercowley (Talk | contribs)


Important note as of 28 January 2012: On some shared host environments ( and perhaps others), the normal Joomla update from 1.7 to 2.5 can intermittently fail with the error "Internal Server Error". In some cases, this can happen in the middle of the file transfer process and cause errors on the site. On, this appears to happen when the server is under a heavy load and the update takes longer than 2 minutes to complete.

Based on recent testing, sites on these slower shared hosts can safely be updated using a free third-party extension called Admin Tools. If you are updating a site on a shared host, please consider using Admin Tools or else use the Manually Copy Program Files method outlined below.

If you have experienced an error during the update, there is a process for repairing the site.

Starting with version 1.6, there are two recommended ways to update your Joomla website.

  • Extension Manager: Update
  • Extension Manager: Install
  • Manually Copy Program Files

Each of these is discussed below. Note: To upgrade from version 1.6.x to Joomla 1.7 please follow this guide.

It is recommended that you follow these steps when updating a production site:

  1. Back up your site before upgrading to a new version. That way, if something goes wrong during the upgrade process, you can easily restore your site to the earlier version.
  2. Review the release notes for the new version to be familiar with what was changed.
  3. Update using one of the recommended methods outlined in this document. These methods install the new program files, delete unneeded old program files, and update the database as needed for the new Joomla version.
  4. Check that the update was successful, using the steps outlined in #Checking Your Site.

Extension Manager: Update Method

Joomla 1.6Joomla 1.7Joomla 2.5

Step 1: Make sure you have a current backup of your site

In many cases, your host will make periodic site backups.

Step 2: Find and install updates

  1. In the back end of your Joomla site, navigate to Extensions → Extension Manager and open the Update tab.
  2. Click on the Purge Cache icon to clear out the cache.
  3. Click on the Find Updates icon in the toolbar. If there is an available update, the screen will list it, similar to the screen shown below.
    Note that available upgrades for extensions used in the site will also show in the list.
  4. Select the update (using the checkbox) and click on the Update icon in the toolbar.
  5. IMPORTANT: This process will take a few minutes. Wait until the process completes and the success message shows, similar to the screen shown below.
  6. Congratulations! At this point, your site is updated. Check that your site is working correctly. If you have any questions before, during, or after the upgrade then please ask them on the Joomla! 1.6 Migrating and Upgrading Forum.

Extension Manager: Install Method

Joomla 1.6Joomla 1.7Joomla 2.5 In some cases it may not be possible to use the Extension Manager: Update method to update your site. One reason for this might be that you are using a non-standard distribution (for example, a distribution with a different default language installed). Another reason might be that your don't have a reliable enough internet connection to support automatic installation.

In this case, you can still do an easy installation using the Extension Manager: Install screen. Like the Update screen, this method will do the database updates automatically and will completely update your system without any further steps.

Step 1: Make sure you have a current backup of your site

In many cases, your host will make periodic site backups.

Step 2: Locate the update file

Locate the required archive file (for example, .zip, .tag.gz, or tar.bz2 archive) for your version. If you are updating to an x.x.0 release (for example, from 1.7.3 to 2.5.0), this will normally be a file like If you are updating within the same release series (for example, 2.5.0 to 2.5.1), then the file will be named something like

At this point, you have three options:

  1. Install from URL
  2. Install from Directory
  3. Upload Package File

Install from URL is the easiest to do. With this option, the upgrade archive is loaded directly by the server, so it works well even if your local computer has a slow or unreliable internet connection.

Install from Directory is the safest method if the server itself has a slow internet connection. With this method, you use FTP to load the unpacked update files into a temporary folder on the server. Then you point to that directory on the server for the installation.

Upload Package File is fairly simple, but it requires that you have a good connection between your local computer and the server.

The screen below shows the Extension Manager: Install screen with the three options labeled.


Install from URL

This option is the easiest, if the archive file is available on a website.

  1. In the Extension Manager: Install screen, enter the URL for the archive file in the Install URL field.
  2. Press the Install button.

The system will work for a period of time, up to two minutes or more for a full version update. Then a message indicating a successful installation will display.

Install from Directory

This option requires that you unpack the archive file in a directory on your server. This is the best method if you have a slow internet connection or you are experiencing timeouts during the update process.

  1. Unpack the archive file in a temporary directory on your local machine.
  2. Upload all of the files in this directory (for example, using FTP) to a temporary directory that is visible to the web server. For example, you can create a sub-directory under the tmp directory in your Joomla root. For this example, let's say the directory on the server is /home/myuser/myjoomla/tmp/upgrade250).
  3. In the Extension Manager: Install screen, enter the full path of the temporary directory (on the server) from step 2 (for example, /home/myuser/myjoomla/tmp/upgrade250).
  4. Press the Install button.

The system will work for a short time (perhaps a minute or less, depending on your server). Then a message indicating a successful installation will display.

Upload Package File

This option requires that you first download the archive file to your local machine.

  1. Download the file to your local computer.
  2. In the Extension Manager: Install screen, click the Browse button next to the Package File field and browse to the archive file.
  3. Press the Install button.

The system will work for a period of time, up to two minutes or more for a full version update. Then a message indicating a successful installation will display.

Checking Your Site

After an update, it is a good idea to check your site to make sure the update was successful. There are two quick checks you can do from the Extension Manager.

Extension Manager: Check Database

This feature was added in version 2.5.0. It checks that your database is up to date with your Joomla programs.

Navigate to Extension Manager: Database. If your database is up to date, you should see a screen similar to the one below:

Database Screen With No Problems

If your database is not up to date, you will see a screen listing the problems found, similar to the one below:

Database Screen With 3 Database Problems

In this case, press the Fix button in the upper right corner. 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.

N.B. If any errors fail to fix then make sure all the database Tables are checked in.

Extension Manager: 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 Extension Manager: Discover. Then click on the Discover icon in the toolbar. The screen should show as follows:

Discover Screen With No Extensions To Install

If so, you know that any new extensions added during the udpate were correctly installed in the database.

If there are uninstalled extensions, they will show similar to the following screen:

Discover Screen With Two Extensions To Install

In this case, check the check 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 Update Problems

If you have problems or errors during the update process, here are some tips.

  • If any database error messages show after the update, be sure to check the Extension Manager: Database tab followed by the Extension Manager: Discover tab. 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 tab and then use the Discover→Install method to check and install any new extensions.
  • If you encounter any errors or problems during or after the update, be sure to check the FAQ for the version you updated to. For example, for version 2.5.0, this will be an article entitled