Skip to end of metadata
Go to start of metadata

See Comparison of Add-On Formats

There are many ways to extend CiviCRM with benefits and drawbacks for each. See Add-on Formats to help decide which is appropriate for your current needs. This page covers "native" CiviCRM extensions - which are NOT restricted to use with a specific CMS. CiviCRM can also be "extended and customized" using CMS-specific extensions - e.g Drupal modules, Joomla components, and WordPress plugins. Refer to the add-on formats page on this wiki and to each CMS's documentation for more information.

More information about CiviCRM Extensions

To find out more about developing CiviCRM Extensions, please visit Create an Extension page.

Enabling extensions

CiviCRM extensions allow you to install additional features for your site. They can provide new functionality in many areas including: Custom Searches, Report Templates and Payment Processors. CiviCRM "native" extensions which have been shared using the Extensions Directory on and which have a stable release compatible with your version of CiviCRM can be installed automatically from Administer >> System Settings >> Manage Extensions.

Configure the extensions directory:
Before installing extensions, you need to configure a directory where your extensions will be stored.

  • Go to: "Administer » System Settings » Directories"
  • fill in "CiviCRM Extensions Directory" field and click "Save" at the bottom of the page.

It's important to put your extensions directory outside of the $civicrm_home directory (the one where your codebase is installed) in order to avoid problems during upgrade. The extensions directory must be readable (so it can execute the extension code) and write-able (so it can download initial and updated versions of extensions) by your web server.

Suggested directory location

Remembering that mysite == default for most single site installs:


This puts it beside the custom_php and custom_tpl directories that many people place in <docroot>/sites/mysite/files/civicrm/. The benefit of being under the files directory here is that it is the standard place for a writeable directory. However, it might be good to move the custom_php and custom_tpl directories out of the files subdirectory and put all of three them beside the files directory in order to prevent things like file uploader extensions from overwriting files in these directories. In other words:







Configure the extensions resource url:
This is the base url through which resources (css, js) of your extensions are accessible to the web.

  • Go to "Administer » System Settings » Resouce URLs".
  • Fill in "," and click "Save".
    Note that this URL corresponds to the same location as the "Extensions Directory" above.

TODO: It should be explained what in the extensions directory should be made web-accessible, if the directory itself is outside of web root.

See the list of extensions:
Finally, you should be able to

  • Go to "Administer » System Settings » Manage CiviCRM Extensions" and
  • See the list of available extensions.

This list is automatically downloaded from available and compatible native extensions on the CiviCRM server. To find out more about a specific extension, click the arrow on the left side of the extension name. This will reveal more details about this extension including the author, release version, release date and licensing.

Other Extension Locations

CiviCRM will find, use and (via the web interface) manage extensions in the url and path location defined above, the "default" extension location for your install.

But CiviCRM will also find and use extensions in other locations. These locations might be populated by other mechanisms - e.g. a vetted subset of all extensions that are made available by default by a hosting provider. Specifically, CiviCRM will scan three directories and their subdirectories for info.xml files, similar to the mechanism that Drupal uses to automatically detect modules (in fact, using almost identical code). The three directories correspond to three extension 'containers', as defined in the function "getFullContainer" of the file "CRM/Extension/System.php"

  1. default : the one identified the settings. But note that although CiviCRM will only manage the extensions in the immediate directory location, it will still find them in subdirectories.
  2. civiroot : the civicrm module code root, i.e. where the civicrm-version.php file is. This allows CiviCRM to be distributed with extensions, and different 'distributions' of CiviCRM to be created.
  3. cmsvendor : a subdirectory 'vendor' of the CMS root (typically, the docroot of the web service). Analagous to the (core) module directory of the CMS. This one is not available for WordPress, only Drupal and Joomla, as noted in the code.



Some extensions listed on are NOT listed in Manage Extensions on your site

 The Extensions Directory on includes several different types of extensions (including Drupal, Joomla and WordPress specific modules). The Manage Extensions function on your site lists and provides automatic installation only for extensions that:

  • Are "native CiviCRM" extensions (not CMS specific)
  • Have been "approved for automated distribution" by one of our moderators
  • Have a "stable" release which is compatible with your version of CiviCRM

If you wish to install "unstable" releases (alpha/beta/pre-release/etc) through the "Manage Extensions" screens, then you can change the extension repository URL. This is the URL used by CiviCRM to fetch the list of available extensions, and it can be customized by editing "civicrm.settings.php":

civicrm.settings.php - Extension Repo URL

Installing a new extension

In order to install a listed extension all you need to do is to click "Install" link next to given extension. The extensions package will be downloaded and set up for use in your system. Extensions may update your database and affect how your CiviCRM site functions. Best practice is to install any new extension on a test copy of your site first and verify that it functions as expected.

Manual installation of native extensions

If you want to install a native CiviCRM extension which is not listed under Manage Extensions automatically:

  • Download the extension package from the download URL provided by the developer
  • Unzip / untar the package and place it in your configured extensions directory
  • If the package has been constructed properly - when you reload the Manage Extensions page the new extension should be listed with an Install link.

Disable automatic installations of extension

For security and policy reasons, you might want to disable the option to download extensions and only rely on the manual installation described above. It has the benefit of also suppressing a couple of possible warning messages: a message if you want to let this folder read only and one if your server does not have the PHP-ZIP extension - "You will not be able to install extensions at this time because your installation of PHP does not support ZIP archives".

To do so, you need to add this following line on your civicrm.settings.php

global $civicrm_setting;
$civicrm_setting['Extension Preferences']['ext_repo_url'] = false;

As a result of disabling the automatic installations of extensions, on the New Extensions page (Drupal), you will see a message "The system administrator has disabled this feature."

Enabling and disabling extensions

If you installed an extension, but don't want functionality provided by it to be available in the system, you can click the "Disable" link next to the installed extension.

Upgrading extensions

If new version of an extension installed in your system becomes available, you will see an "Upgrade" link next to it – clicking it will upgrade the extension's source code. If there are also database changes, then a new alert will prompt you to apply them as well.

Upgrade Details

The mechanics of the upgrade process depend on a few rules:

  • If the extension is a 3.x-style specialized extension (i.e. "Payment Processor Extension", "Custom Search Extension", or "Report Extension"), then both the source code and the metadata will be uninstalled and reinstalled. (3.x-style extensions should not have other data.)
  • If the extension is a 4.2+-style module extension, then the source code will be uninstalled and reinstalled, but the metadata will be modified in-place, and (if applicable and if approved by the admin) the database will be upgraded using hook_civicrm_upgrade (or, more specifically, using an Upgrader class).

Uninstalling extensions

In order to uninstall extension, you need to disable it first - once disabled, you will see the "Uninstall" link. Click it in order to completely remove the extension from your system, including permanent deletion all of its custom data. To preserve the data, take a backup before uninstalling.

How to use extensions

Some of the extensions available for CiviCRM include:

  • None
  1. May 17, 2013

    Michael or Joe,

    Can you clarify the upgrade process. From the description on this page it sounds like the existing extension is literally uninstalled and a the new one installed.

    We're working on the Civi Discount extension and this process would cause signification data loss, since the extension uninstall process drops the tables that contain the configured discounts.



    1. May 17, 2013

      Dave, you're very right that that is not appropriate. I'll ping Tim Otten about this as well.

    2. May 17, 2013

      Yes, that would be a problem, but the documentation is old. The uninstall+reinstall process applies to the 3.x-style specialized extension types ("Payment Processor Extension", "Custom Search Extension", "Report Extension"). I suspect there wasn't much concern because specialized extension had less data to worry about (e.g. a custom-search doesn't save anything to the DB except its own registration record).

      In 4.2+, we introduced generic "module" extensions (like CiviDiscount) which do have data, so we changed the process. 4.2 introduced two major changes:

      • Code upgrades for module extensions do not run the uninstall/reinstall process.
      • After performing a code upgrade, we check for database upgrades (hook_civicrm_upgrade) and prompt the user before executing DB upgrades.

      (Historical aside: In 4.1, we had experimental support for module extensions; 4.1 could be problematic here, but we never distributed/publicized 4.1 module-exts. In 4.3, we significantly reorganized the extension manager, but the final behavior in 4.2 and 4.3 should be the same.)

      1. May 17, 2013

        Thanks, Tim. I did a few more edits to incorporate these points into the text.

  2. Mar 13, 2014

    Changed $civicrm_setting['Extension Preferences']['ext_repo_url'] = '{ver}|cms={uf}|status='

    but I still do not see most of the extensions.  Do I have to list all status types?

  3. Aug 10, 2015

    To repeat part of shawn holt's point from March 2014, what values should be inserted for \{uf\} and possible other specific statuses? I have managed to get 4.5 and 4.6 to work for \{ver\}. However, trying to use D6 WP and D7 and Drupal for \{uf\} has not worked.