Skip to content

Upgrading CiviCRM for Joomla

Use this document to upgrade CiviCRM installations on Joomla to the latest CiviCRM release.

Before upgrading

Make sure you have done the steps listed in before upgrading first.

Known Issues

If using a version prior to 4.7.29 you need to apply the following two PRs after installation but before running the upgrader:

  • #11062 (If using Joomla > 3.8.1 otherwise CRON/CLI won't work).
  • #11236 (If using Paypal IPN).

Download the latest code

  1. Go to the CiviCRM website

  2. Select the latest currently available CiviCRM tarball for Joomla.

    Example: civicrm-x.x.x-joomla.zip

    Note

    You may notice a file on the named something like civicrm-x.x.xx-joomla-alt.zip the -alt version does not require .zip functions compiled into PHP by your hosting company. If you get errors like "Your PHP version is missing zip functionality", then try the -alt version.

  3. Save this file in <joomla_root>/tmp/.

  4. Unzip and check that it created a directory called com_civicrm in <joomla_root>/tmp.

Backup your settings files

The before upgrading steps describe steps for backing everything up in case something goes wrong during the upgrade. In particular, note that Joomla has two settings files for CiviCRM and they should both be backed up:

  • <joomla_root>/components/com_civicrm/civicrm.settings.php
  • <joomla_root>/administrator/components/com_civicrm/civicrm.settings.php

Copy these files to a location outside your Joomla project.

Install the Extension

  1. Login to your Joomla Administrator site.
  2. From the menu choose Extensions » Manage » Install
  3. Use the Install from Folder tab and enter the full path to the un-zipped com_civicrm directory, which should be something like JOOMLA.x_ROOT/tmp/com_civicrm. If your temp directory is configured correctly you should only need to add "com_civicrm" to the prepopulated path.
  4. You should see "CiviCRM successfully installed" message.

The steps above will install CiviCRM directly on top of your existing installation, overwriting existing files. This means that files from previous releases that are no longer required are not removed. Generally this is not a problem but it can cause failures. If this happens you can either:

  • Find and manually remove the outdated files. Check on StackExhange or Chat to see if others are reporting the same problem. The CiviCRM log may indicate which files are causing the problem, or you can look at the modification timestamp of the files. Obviously keep a copy of anything you remove in case you need to revert.

  • Uninstall and reinstall CiviCRM. This will not affect your CiviCRM data but:

    1. You will need to save your two civicrm.settings.php files before you uninstall, then copy them back after reinstalling.
    2. It will reset all the CiviCRM permissions assigned to your Joomla groups. Make a record of those first so you can reapply them. If however you didn't do that and are now regretting it, you can reload a backup of your Joomla database, or start again from the settings.

Update localisation files

  1. If using localization, also download the latest version of the localization files. See the CiviCRM Localisation page about how to install files for running CiviCRM in languages other than American English.

    Go to <joomla_root>/administrator/components/com_civicrm and extract civicrm-x.x.x-l10n.tar.gz

Clear the file cache

Delete all cache files in <joomla_root>/media/civicrm/templates_c on your server before proceeding with the update script.

Upgrade the database

After the component installation completes click the link to run the database upgrade script. You may also point your web browser to the following URL (you should already be logged in to Joomla with administrator-level permissions):

http://example.org/administrator/index.php?option=com_civicrm&task=civicrm/upgrade&reset=1

You should see an Upgrade successful message when the upgrade completes.

  1. If you receive any errors during the process, please note the exact error message and check for solutions on Stack Exchange or Mattermost.
  2. Now click the Return to CiviCRM home page link.
  3. You should be up and running with the latest CiviCRM version. Confirm by checking the version and revision in the page footer. Note that you may need to refresh the browser screen a couple times to clear out your local cache and ensure the layout loads correctly.
  4. Take some time to browse the CiviCRM features that your organization uses. If you notice unexpected behaviors or error messages, refer to the trouble-shooting section below.

Restore settings file changes

Review the backup versions of the files below and compare them with the new versions just installed. In particular, make sure your site key value was retained and any of the configuration options found in those files are still intact.

  1. /components/com_civicrm/civicrm.settings.php
  2. /administrator/components/com_civicrm/civicrm.settings.php

Post upgrade

See these steps to take after upgrading.