Joomla! Documentation™

Overview

Warning!

Always back up your site before updating.

The recommended way to update installations of Joomla! is to use the Joomla Updater component found in the Components menu of your site Administrator(Method A) introduced in J2.5.4. Updating earlier versions need to use Install Method (Method B) or Manual Upgrade(Method C).

Browse to Components, Joomla Update

If an update is available there will be a message indicating this and a button to press. Otherwise for J2.5 go to Extension manager => Update and press Purge cache.

Click on the "Install the Update" button and allow the update to run

When it has completed you may need to refresh your screen or empty your browser cache to adjust for template CSS changes.

Note: Joomla! will notify you on your administrator home page (control panel) when an update is needed, but it will not do the update for you. You need to press the button to start the update.

Recommnended Steps and actions: 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. Clear your browser cache and check that the update was successful, using the steps outlined in the Checking Site tab.

Method A - Update Method

This is the easier way, also called One click update

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

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

Step 2a: Find and install updates

1. If your site is prior to 2.5.4, see Step 2b instead
2. In the back end of your Joomla site, navigate to Components → Joomla Update.
3. Click on Install the Update
   
4. IMPORTANT: This process will take a few minutes. Wait until the process completes and it tells you that you are already on the current release, similar to the screen shown below.
   
5. Congratulations! At this point, your site is updated.

Important: Clear your browser cache and check that your site is working correctly. See below Checking Your Site

Step 2b: Find and install updates (Prior to updating 2.5.4)

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.

Important: Clear your browser cache and check that your site is working correctly. See below Checking Your Site

Method B - Install Method

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 Joomla_2.5.0-Stable-Update_Package.zip. 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 Joomla_2.5.0_to_2.5.1-Stable-Patch_Package.zip.

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 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.

1. Congratulations! At this point, your site is updated.

Important: Clear your browser cache and check that your site is working correctly. See below Checking Your Site

Method C - Manual Upgrade

This method is similar to the old method for updating Joomla versions. Here we want to replace the existing program files with the files from the update archive. The advantage of this method is that it will work on slower shared hosts. The disadvantage is that it requires more work by the system administrator.

Important: This method can also be used to repair a site where the automatic update failed due to a server timeout.

Copy the New Program Files to Your Site

There are two ways you can do this.

1. Copy the archive file to the root directory of your site and unpack the archive. The update archive will be named something like Joomla_2.5.0-Stable-Update_Package.zip. Note that you need to tell the system to replace any existing files. For example, in GoDaddy.com, use the FTP File Manager to upload the update file and then use "Unarchive" to unpack it. Check the box "Overwrite existing files".
2. If you don't have the ability to unpack the archive on the server, create a temporary directory on your local machine and unpack the archive file there. Then FTP these files to the root directory of your site, overwriting the existing files.

Update the Database

At this point, you should be able to log into the back end of your site with the new version installed. However, you are not done. Navigate to Extension Manager: Database. You will initially have Database problems when you check the Database, similar to the screen below.

Database Screen Before Fix

This is expected. Click on the Fix icon to correct the problems. Now the screen should show that the database is up to date.

Install New Extensions

Navigate to Extension Manager: Discover and click on the Discover icon in the toolbar. If the updated version has new core extensions, new extensions will be listed, as shown below.

Discover Screen Before Install

Select all the extensions and click on the Install icon in the toolbar. The system should display a success message similar to the screen below.

Discover Screen After Install

Update the #__extensions Table

At this point, your site is updated. However, there is one more thing to do. The site will think it needs to be updated because a value in the #__extensions table is wrong. To fix this:

• Using phpMyAdmin or a similar tool, edit the row of the #__extensions table where the id column is '700'. (Note that the table prefix will be different in your site. For example, if your table prefix is "jos_", then the table will be called "jos_extensions".
• In the manifest_cache column, you will see the old version in the text (for example, "version":"1.7.3"). Change this to the new version (for example, "version":"3.1.4"). Be careful to not change anything else in this column.
• To check that this was successful, navigate to Extension Manager: Update and click Check for Updates. You should not see the current Joomla version in the list.

At this point, your site should be updated correctly.

Checking Site

This is required for method A and B! After an update, it is a good idea to clear your browser cache snd 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

If you have any questions before, during, or after the upgrade then please ask them on the Joomla! 1.6 Migrating and Upgrading Forum.

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

• Clear your browser cache as there may have been changes to the css or javascript that will need to be reloaded by your web browser.
• 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 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 http://docs.joomla.org/Category:Version_3.0_FAQ.

Known problems

If your site has been migrated from J!1.5 earlier on, then you might experience problems when trying to update from 2.5.x to 3.1.5.

These instructions assume you have correctely prepped your joomla 2.5.11 install and are still having issues. (ie you have upgrade your extensions and removed those which are not compatable with j3.x etc...)

The Error

Due to the different variations of installed components, you might not see the exact error below but one very similiar.

Code: 0 - An error has occurred.

SQL=INSERT INTO `jos_menu` (`id`, `menutype`, `title`, `alias`, `note`, `path`, `link`, `type`, `published`, `parent_id`, `level`, `component_id`, `checked_out`, `checked_out_time`, `browserNav`, `access`, `img`, `template_style_id`, `params`, `lft`, `rgt`, `home`, `language`, `client_id`) VALUES (23, 'main', 'com_tags', 'Tags', '', 'Tags', 'index.php?option=com_tags', 'component', 0, 1, 1, 29, 0, '0000-00-00 00:00:00', 0, 1, 'class:tags', 0, '', 45, 46, 0, '', 1);

the upgrade from j2.5.11 can be a difficult one if you arrived at j.25 via a migrated j1.5.x joomla install. the reason is that for some reason the jupgrade did not correctely migrate menu (or other possibly) id's correctely.

when you do a fresh install off joomla 2.5.11 the menu items up to 200 are reserved for future joomla menu updates for the core. No user content starts until id 201. The user created menus or in this case the demo data start at 201. some versions of joomla possibly start this at id 100

now in my case there is no gap between the core and the user data menu ids (ie i have some user menus in the 0 - 200 range) and this can rear its head when you do an upgrade because the guys at joomla expect 0-100 or 0- 200 to be empty so issues like the on i have do not happen and they can put their stuff in there.

one way of detecting this error without diving into the database is the lack of the joomla update component menu in the admin panel. You can correct this missing item by following this article -insert link-- but it will delete the menu item that is already there. If you know what you are doing just look in jos_menu and see if the range 0-200 only has joomla core stuff in it.

now my issue is when the update has almost finished it says there is a duplicate entry, in my case it is a jmedia menu item

Solution

It is the menu items that causes the upgrade issue for me.

later version of j2.5 made all new 'user content' menu items install in the jos_menu id 200+ region so this will never be an issue, but for those of use who have migrated from joomla 1.5 with jupgrade to an early version of j2.5 (early versions of jupgrade had issues in migrating menu id numbers), here is the fix

The errors in the database need fixing. But you can sucessfully upgrade to joomla 3.0.3 and then make the changes. I believe that it is after j3.0.3 the 'joomla extension' and 'joomla core' quick icon items are added. However i would make the changes to the j2.5.11 first. This note is really for reference for those on j3.0.3 having similiar issues and apart from the obvious the fix is still the same.

Pre-requisites - backup, backup, backup etc.. - upgrade your joomla 2.5 to the latest version, should be 2.5.11 at the time of writing this

step 1 - copy all of you menu's (only those below 200)

NB: - there is a batch copier at the bottom of the menu page - move keeps the same id, only top level seems to get the number on the end)

How To: - create a new menu for each of the menus you need to copy the menus (via menus tab) i just add a 'c' at the begining menutype of the menu alias so no duplicates are created - filter the menu to copy at the top - make sure 'display all' is set - select all the shown menu items - go to the batch thing at the bottom (of menu items tab) - select the new target menu, a blank one that begins in your 'c'- now copy the menu - keeping 1 windows open with the list of menus, open the module manager and fiter by type, selecting menu - edit each affected module (by editing the old menu module posistion just on the right of each menus entry) and swap from the old menu to the new 'c' menu - once done check the new menus are working as they should - if one of the affect menus is default, make sure to swap this aswell - some of the menus items will get a 2 added on to them (to prevent duplicate alias). you will have to remove this manually - delete the old menus from menu manager and make sure they are removed out of trash aswell - now all the menus from below 200 should be removed - in the databse you might have some menu items that were not deleted properely at some point in the past and should be removed via phpmyadmin (only if you know what you are doing) - reassign all menu modules that have been affected to their new menu's (ie the ones with 'c' in front) - delete the old menus (to avoid confusion) - remove the letter 'c' from the beginning of the new module names (the menu and mosule will still be linked) - rename the new modules to remove the word copy out of thier name etc..

Remaining Steps

- perform the joomla updater component fix

As mention before the joomla updater might be missing. To fix this you need to run the following sql script to add the entery back in. You by now should have an empty 0 - 200 menu id range. This is correcting one of those damaged enteries.

info from: https://www.akeebabackup.com/documentation/troubleshooter/atj25update.html http://docs.joomla.org/Joomla_Update_Missing_in_from_Admin_Menu

- additional missing menu items. I checked the menu items on a fresh install of joomla 2.5.11 and discovered that core menu items go up to 22. (i think in later version of j3 tags is added in at id 23)

I had a missing item, Smart Search. here is the code i used to fix the missing item: Code:

INSERT INTO `j25_menu` (`id`, `menutype`, `title`, `alias`, `note`, `path`, `link`, `type`, `published`, `parent_id`, `level`, `component_id`, `ordering`, `checked_out`, `checked_out_time`, `browserNav`, `access`, `img`, `template_style_id`, `params`, `lft`, `rgt`, `home`, `language`, `client_id`) VALUES
(21, 'menu', 'com_finder', 'Smart Search', '', 'Smart Search', 'index.php?option=com_finder', 'component', 0, 1, 1, 27, 0, 0, '0000-00-00 00:00:00', 0, 0, 'class:finder', 0, '', 41, 42, 0, '*', 1);

the quickest way to get code like this is to use phpmyadmin to export them from a fresh copy of joomla j2.5.11

- now perform the upgrade to 3.1.1 - check database is correct and inspect your content - file you j2.5.11 backup somewhere safe - backup your new j3.1.1 site - file you j3.1.1 backup somewhere safe - click on the clear cache (i admin) link to allow the new admin menu to come properely - done

If the update icons are missing on the dashboard. this is because the plugins need to be enabled. on a default 3.0 install they are enabled by default.

Go to the plugin manager and enable:

- Quick Icon - Joomla! Update Notification - Quick Icon - Joomla! Extensions Updates Notification

Final Thought

You possibly need to reinstall a component over the top if you get issues. i did, in particular k2. i had updated it to the latest version before upgrade (cannot uninstall it because it wipes the database)

Also if you have tried to update, and it failed, then you have to make shure that no tables from the update are left behind in the database, because they will also conflict!

<headertabs/>