Skip to content

Extensions

CiviCRM extensions allow you to install additional features and functionality for your site. Because they 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.

See Comparison of Add-On Formats

There are many ways to extend CiviCRM with benefits and drawbacks for each. 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 Packaging Formats page and to each CMS's documentation for more information.

More information about CiviCRM extensions

To find out about developing CiviCRM extensions, see Developer Guide: Writing Extensions.

Where do extensions come from?

Extensions come from various sources:

  • CiviCRM Core: The official release of CiviCRM includes several "core extensions". These are always available.
  • CiviCRM Extension Directory: Members of the CiviCRM community may list extensions on the public directory. After a general peer review, these become available for in-app download.
  • Other Sources: Administrators may manually add extensions from other sources. This may include:
    • New (un-reviewed or un-released) items from the Extension Directory.
    • Extensions from https://lab.civicrm.org/extensions
    • Extensions from github.com, gitlab.com, codeberg.org, or similar third-party system
    • Private extensions developed internally by the user-organization.

Extension states: Enabled/Disabled/Uninstalled

The Administer » System Settings » Extensions page provides a list of extensions and their statuses.

Extensions need to be installed (the code files are on the server in the right place) and Enabled to be usable. Enabling an extension will create any data that the extension needs (e.g. new entity types, custom fields etc.).

Having been enabled you may disable and then uninstall an extension. Disabling means its functionality is not available, but typically any data it created is still there (even if it's unreachable). Typicaly, when you uninstall an extension, it will remove any data it created, however uninstalling does not delete the code files. Only after uninstalling an extension can you safely remove its code.

How to install an extension

You need to put the extension's code in a directory on your server configured for this purpose. You can see/change this from Administer » System Settings » Directories. Each extension lives in its own directory.

Installing extensions that are available in-app

Clicking Install on one of the extensions listed from the Administer » System Settings » Extensions page will download the code to your extensions directory and then enable it.

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.

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

Note

Systems Administrators need to know that for this to work, the extensions directory needs to be writable by the user that the webserver runs as (e.g. www-data)

Installing from the command line

This process involves:

  1. Getting the code.
    This is covered in the following two sections following,

  2. Enabling the extension.
    Once the extension is in place you can either visit Administer » System Settings » Extensions, click Refresh, and then your extension should then be listed ready for you to click Install, or you can enable the extension from the command line using cv en <EXTENSION_NAME>.

A shortcut command line process is

cv dl <http://URL.zip>

This command will locate the appropriate location, download and unzip the code, and then enable the extension.

Installing from a .zip file

For example, that you downloaded manually from civicrm.org/extensions. Simply unzip the file in your extensions directory to make it available to be enabled.

Installing from a code repository (GitLab, CodeBerg, GitHub, ...)

Code repositories hold the source code for extensions as it changes over time ("version control"), and they usually offer a means to track bugs/issues and features to help co-ordinate teams of people working to improve the code. Most of them are based around a version control system (VCS) called Git.

They all share similar concepts. The best place to look for a .zip file you can download that bundles up all the files you need is the Releases page (sometimes you find this via aTags page). Releases are deliberately published snapshots of the code, e.g. "version 1.2". It's important to grab a .zip from the releases page if you can because:

  • The developer might have included some important information, such as version compatibility, change notes, warnings, stability notices or other important notes on the releases page that you might miss if just downloading the latest code. The latest version might require a different version of CiviCRM to yours.

  • The .zip archives available from the releases pages might include files that are not to be found in the code repository itself (e.g. it might include 3rd party libraries.)

If there are no releases published and you want to try the code, these code repositories will offer a download button to download the latest version ("head" of a "main" or "master" branch) of the code, but it's much safer to use a published release whenever possible.

If you're a developer wanting to work on the code, or you just prefer to use git on the commandline to manage your extensions, you probably know that you can git clone <URL> to get the source code, and to read the README or other instructions in case there are further steps (e.g. to bring in 3rd party dependencies).

Upgrading extensions

Extensions upgrades require replacing the current code with new code, and then, where necessary, applying database upgrades.

Tip

Because upgrading extensions may change your database, it's a good idea to backup your database before applying upgrades, and ideally try the upgrade on a test copy of your CiviCRM instance before applying on your production/live server.

If new version of an extension installed in your system and published on civicrm.org/extensions becomes available, you will see an "Upgrade" link next to it. Clicking this will upgrade the extension's source code and if there are database changes required an alert will provide a link for you to click to apply them as well. All done!

Warning

If you installed an extension published on civicrm.org/extensions but you did so from the commandline, there is a chance that the in-app upgrade fails due to file permissions. Read on.

Upgrading extensions installed from the command line

Replace the extension's code (by downloading a new .zip and replacing the original directory with the unzipped new archive, or using git pull/merge/checkout), then run cv ext:upgrade-db to do the database migrations.

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.

Advanced: Configuring the location of the extensions directory

Each CMS platform (WordPress, Drupal, Joomla, Backdrop ...) has a suggested default directory, but you can use a different location if you prefer/need.

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

Tip

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.

The default locations are:

  • Drupal: <docroot>/sites/<mysite>/files/civicrm/ext Remembering that <mysite> is 'default' for most single site installs:

  • Joomla: <docroot>/media/civicrm/ext

  • WordPress: <docroot>/wp-content/uploads/civicrm/ext

Configure the extensions resource URL

This is the base URL through which resources (css, js) of your extensions are accessible to the web; it corresponds to the same location as the "Extensions Directory" above.

  • Go to Administer » System Settings » Resource URLs.

  • Fill in Extension Resource URL and click Save.

If you positioned your extensions directory outside of the docroot, you'll need to put in place some special server configuration to make extensions' public assets accessible by http.

Advanced: 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. 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 (e.g. SearchKit), 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.

Advanced: Using unstable (alpha/beta/pre-releases etc.) through the Manage Extensions screens.

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":

```
<?php
...
global $civicrm_setting;
// NB: for both Option A and Option B, you can use 4.5 or 4.6 etc as the {ver}
// Option A: Default repository URL; civicrm.org will make its best recommendation for stable/compatible extensions
$civicrm_setting['Extension Preferences']['ext_repo_url'] = 'http://civicrm.org/extdir/ver={ver}|cms={uf}';
// Option B: Customized repository URL which filters on "any release status" (stable, alpha, beta, etc)
$civicrm_setting['Extension Preferences']['ext_repo_url'] = 'http://civicrm.org/extdir/ver={ver}|cms={uf}|status=';
...
```

Advanced: 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 civicrm/admin/extensions?reset=1 (Drupal), you will see a message "The system administrator has disabled this feature."