About this document

CiviCRM follows the Drupal community's decisions around which versions of Drupal receive support. Drupal 8 and 9 are no longer supported, but Drupal 7 until Jan 5, 2025 and Drupal 10 are supported.

This guide covers standard installation of CiviCRM on an existing Drupal site. Before starting, you must have completed these tasks:

Installed Drupal and...
Reviewed the CiviCRM requirements

Get the code for Drupal 10¶

Drupal 10 sites are typically administered with Composer. Composer is a dependency management tool which can add, upgrade and remove software packages for your site.

If composer is properly installed, then these example commands will add latest CiviCRM version to D10:

cd /var/www/d10.example.org
composer config extra.enable-patching true
composer require civicrm/civicrm-{core,packages,drupal-8}
composer require civicrm/cli-tools

More detail: Enable patching

A handful of packages used by CiviCRM require extra patch-files.

This is possible with the popular cweagans/composer-patches plugin. However, you must opt-in to enable it.

Install CiviCRM without any translations¶

To install CiviCRM without any translations we use the command line tool cv and we assume you already have an empty database.

Change the following in the command below:

https://d10.example.org change this to your civicrm url
database_user change this to your database user
database_pass change this to the password of your database user
civicrm_database change this to name of your civicrm database

cv core:install --cms-base-url="https://d10.example.org" --db="mysql://database_user:database_pass@localhost:3306/civicrm_database"

Install a translated CiviCRM¶

To install a translated CiviCRM on Drupal 10 requires the following first downloading the translation files.

Change the following in the command below:

nl_NL to your language, e.g. fr_FR, or nl_BE etc...
https://d10.example.org change this to your civicrm url
database_user change this to your database user
database_pass change this to the password of your database user
civicrm_database change this to name of your civicrm database

mkdir -p web/sites/default/files/civicrm/l10n/nl_NL/LC_MESSAGES
curl -Lss -o web/sites/default/files/civicrm/l10n/nl_NL/LC_MESSAGES/civicrm.mo https://download.civicrm.org/civicrm-l10n-core/mo/nl_NL/civicrm.mo
export CIVICRM_L10N_BASEDIR=/var/www/d10.example.org/web/sites/default/files/civicrm/l10n
cv core:install --cms-base-url="https://d10.example.org" --db="mysql://database_user:database_pass@localhost:3306/civicrm_database" --lang="nl_NL"

Get the code for Drupal 9¶

Drupal 9 reaches end of life status soon

If you start implementing a new CiviCRM environment you might want to start with Drupal 10 or a different CMS. Check out Drupal 9 end of life status

Drupal 9 sites are typically administered with Composer. Composer is a dependency management tool which can add, upgrade, and remove software packages for your site.

CiviCRM is published as a suite of related packages. Our goal is to use Composer to add CiviCRM's packages to the D9 site.

If you do not work regularly with D9+Composer, then you should take a refresher before installing CiviCRM.

Quick and dirty introduction to D9 with composer

Composer requires shell access to the D9 site. It defines a command composer.

Many D9 sites are initialized via composer, which means that composer is already available. This can be confirmed in the shell by running composer --version:

$ composer --version
Composer version 1.10.13 2020-09-09 11:46:34

It is possible that your system does not have composer -- for example, if you used a tar-based installation of D9, then you may never have needed composer before.

If composer is missing, then you must download and install it first. Additionally, you probably need to set composer's memory limit high enough for D9.

Once you have composer, you need to navigate to the composer-root. You can recognize it by the following:

It has the files composer.json and composer.lock.
It has a subfolder vendor/.
It usually has a subfolder web/ (the web-root); alternatively, it may be the web-root.

A typical file-hierarchy might look like:

/var/www/d9.example.org/                Composer-root
/var/www/d9.example.org/composer.json   Composer-configuration
/var/www/d9.example.org/composer.lock   Composer-configuration
/var/www/d9.example.org/web/            Web-root (usually)
/var/www/d9.example.org/vendor/         Downloaded packages

To work with composer and D9, you must open a shell and navigate to the composer-root, e.g.

cd /var/www/d9.example.org

If composer is properly installed, then these example commands will add CiviCRM to D9:

cd /var/www/d9.example.org
composer config extra.enable-patching true
composer config minimum-stability dev
composer require civicrm/civicrm-{core,packages,drupal-8}:'~5.42'
composer civicrm:publish

You should adjust the example path (/var/www/d9.example.org) and the example version (~5.42) as needed.

Install CiviCRM before Drush

You should install CiviCRM packages before installing Drush to avoid dependency issues with symfony/finder or symfony/filesystem. If you've already got Drush installed and want to install CiviCRM remove Drush first.

composer remove drush/drush
composer require civicrm/civicrm-{core,packages,drupal-8}
composer require drush/drush

If you'd like more details to understand these commands or common errors, then please drill-down below.

More detail: Enable patching

A handful of packages used by CiviCRM require extra patch-files.

This is possible with the popular cweagans/composer-patches plugin. However, you must opt-in to enable it.

More detail: Package stability

For any package in composer, there may be several available versions. Some have an official, well-defined name or number (e.g. v1.2.3), and these are called "stable" versions. Other versions have an interim name or number (e.g. v1.2.alpha1 or dev-master) indicating that additional testing is appropriate.

As a general rule, a new composer deployment will (and should) only use "stable" versions. CiviCRM, too, is generally built around "stable" dependencies. However, in some exceptional cases, CiviCRM requires an interim release of some libraries.

composer.json has two options which affect this: minimum-stability sets an absolute baseline, and prefer-stable expresses a general preference. Setting minimum-stability to dev enables to installation to proceed when there are exceptional cases. Setting prefer-stable to true means that composer will use stable releases whenever it can.

More detail: Compilation tasks

When you first install or upgrade to CiviCRM 5.31+, composer will prompt for permission to run CiviCRM compilation tasks. We recommend that you select [a]lways.

If you wish to suppress the prompt, see Composer Compile Plugin: Managing the root package (for site-builders).

More detail: Required packages

Package	Description
`civicrm/civicrm-core`	The primary CiviCRM codebase
`civicrm/civicrm-drupal-8`	The integration module for CiviCRM and D8/D9
`civicrm/civicrm-packages`	A collection of third-party/legacy packages used by CiviCRM
`civicrm/civicrm-asset-plugin`	A tool which automatically copies JS+CSS assets from CiviCRM to D9's `web/` folder. Required by civicrm/civicrm-drupal-8

More detail: Version constraints

The primary CiviCRM packages (civicrm-core, civicrm-drupal-8, civicrm-packages) have synchronized versions. If one package is installed with v5.30.1, then the others should also be v5.30.1.

The following expression references the three packages and applies the same version-constraint to each:

civicrm/civicrm-{core,packages,drupal-8}:'~5.42'

The expression ~5.42 is a version-constraint. It means that composer will install approximately v5.42. It may install a newer patch-release (e.g. 5.42.1) or a newer minor-release (e.g. 5.43.0). However, it will avoid major-releases (e.g. 6.0.0).

Many composer tutorials rely on composer to automatically choose package-versions. This is not recommended for CiviCRM/D9. Instead, package versioning should be explicit to ensure that:

CiviCRM versions remain synchronized.
CiviCRM stable releases are preferred over developmental releases.

Get the translations for Drupal 9¶

I18n & L10n on Drupal 9

If installing with the GUI it is currently only possible to install CiviCRM in English (US) on Drupal 9. Adding the language files involves breaking with Composer best practices by writing the contents of the civicrm-l10n tarball into vendor/civicrm/civicrm-core or configuring the civicrm.l10n directory path after you install and placing the contents of the civicrm-l10n tarball into the configured directory.

Here Be Dragons...

The following steps are provided as an example - they are not supported or widely tested and may leave your site in a broken state. You use them at your own risk. No. Seriously...

You will also have to repeat these steps every time you upgrade CiviCRM.

The warnings above notwithstanding to install CiviCRM with i18n on Drupal 9 requires the following additional steps to prepare:

Add cv to your Drupal 9 Site with: composer require civicrm/cv.
Grab the localisation (l10n) files and unpack the l10n and sql subfolders into vendor/civicrm/civicrm-core/
- You'll find the l10n files on the CiviCRM Download page or from https://download.civicrm.org/civicrm-VERSION-l10n.tar.gz where VERSION is a recent version of CiviCRM.
Example:
```
wget https://download.civicrm.org/civicrm-5.27.2-l10n.tar.gz
tar -zxvf civicrm-5.27.2-l10n.tar.gz
cd civicrm/
cp -R l10n/ ../vendor/civicrm/civicrm-core/
cp -R sql/ ../vendor/civicrm/civicrm-core/
cd ..
rm -rf civicrm/
```
If you've done this correctly, you should end up with vendor/civicrm/civicrm-core/l10n and vendor/civicrm/civicrm-core/sql/
- You can remove any languages you don't need by deleting them before copying the l10n and sql folders.

Now we move onto Installing CiviCRM - Command line install

Run the installer for Drupal 9¶

The installer verifies requirements, prepares the database, and initializes the configuration file. You may run the installer through the web interface (which is simpler) or the command-line interface (which has more options).

Run installer via Drupal 9 web UI

Installation options are very limited

Currently there is no interactive installer for CiviCRM on Drupal 9, so the installer uses a firm set of defaults, e.g.

English Language Data: It only installs data for US English. It cannot install data for other languages.
Shared Database: It only uses the shared CMS database. It cannot use a separate MySQL database for CiviCRM.
No Sample Data: It only installs an empty, baseline dataset. It cannot install sample data.

If you need to configure any of these options, then use the command-line installer.

Write permissions

It is critical that your web-server user is able to write to the web/sites/default/ directory in order to create civicrm.settings.php and that you have an appropriate value for execution time(s) and memory limit(s) as any interruption to the installer can (and will) result in an unusable install and require remedial steps to correct or a full reinstall! By default on Drupal 9 this directory path is not writable by default, before installing you should ensure you grant write access to your web server user. With, e.g: sudo chmod u+w web/sites/default.

For multisite installations you'll also need to ensure your web server user has write access to additional sites e.g: sudo chmod u+w web/sites/site2.example.org.

Login to your Drupal site with administrator permissions.
Navigate to Manage >> Extend or point your web browser to the following URL:

https://example.org/admin/modules/
Find "CiviCRM Core" and enable it (you can optionally enable "CiviCRM Theme" to set a theme just for CiviCRM.)
At the bottom, click "Install". (Note: This may take a few moments to execute.)

Run installer via command-line

CiviCRM has a command-line administration tool, cv, which can perform installation. For details, see command-line installer.

Get the code for Drupal 7¶

The CiviCRM download page provides a pre-built archive for use with Drupal 7. A typical archive file is ~20mb and looks like civicrm-X.Y.Z-drupal.tar.gz. It contains a folder named civicrm/.

In Drupal 7, there is a folder for storing add-on modules: DRUPAL_ROOT/sites/all/modules.

Our goal is to download the archive and extract into this folder. Here are a few example ways to download and extract:

Download via web-browser

This method does not require shell access on the server. You may adapt based your server's arrangement.

On the CiviCRM download page, click the link for CiviCRM / Drupal 7. Save the file locally.
Extract the archive locally. For example, in a Linux workstation, one might say:
```
cd ~/Downloads
tar xvzf civicrm-X.Y.Z-drupal.tar.gz
```
Observe the new folder civicrm/.
Using your favor file-transfer system (SSH/SFTP, rsync, git, mv, etc), transfer the civicrm/ folder to DRUPAL_ROOT/sites/all/modules.

Download via curl + tar

This method require shell access to the Drupal server.

On the CiviCRM download page, note the current version.
In the shell, navigate to the Drupal module folder (adjust as appropriate):
```
cd DRUPAL_ROOT/sites/all/modules
```
In the shell, run the curl and tar commands. Adjust the version X.Y.Z to the appropriate value.
```
curl -L "https://download.civicrm.org/civicrm-X.Y.Z-drupal.tar.gz" | tar xvz
```

Download via Drupal web UI

This is the easiest way for a new administrator. However, it may not work in all deployments or all versions. For example, if the Drupal server has a locked-down configuration, then it may encounter permission errors or timeouts. The only way to find out is to try.

On the CiviCRM download page, right-click the link for CiviCRM / Drupal 7. Copy the URL.
Login to your Drupal site with administrator permissions.
Navigate to Modules >> Install new module.
Paste the URL
Click "Install"

This may not work with CiviCRM 5.13-5.30

In CiviCRM versions 5.13 - 5.30, the prebuilt tarball included a symlink which is not accepted by the Drupal 7 installer. This should work again in 5.31.

The "Upload"/"Browse" option is unlikely to work.

The Install new module page provides another option for uploading the archive from your local computer. In a default PHP configuration, the upload limits are too conservative to accept the CiviCRM archive.

In all cases, the final outcome should be the creation of a new folder

DRUPAL_ROOT/sites/all/modules/civicrm

Get the translations for Drupal 7¶

The basic CiviCRM release includes support for US English (en_US). To use another language or dialect, please download and extract the translation files.

Run the installer for Drupal 7¶

The installer verifies requirements, prepares the database, and initializes the configuration file. You may run the installer through the web interface (which is simpler) or the command-line interface (which has more options).

Run installer via Drupal 7 web UI

Enable the "CiviCRM" module
- Login to your Drupal site with administrator permissions.
- Navigate to the "Modules" page (admin/modules).
- Find "CiviCRM" and enable it.
- At the bottom, click "Save Configuration".
After enabling, the status message will display a link to "configure CiviCRM". Click it.

What if I didn't notice the link?
Use the URL bar. Navigate to the civicrm page (e.g. https://example.com/civicrm).
The CiviCRM installer will open.
- If there are unmet requirements, the installer will list them. Consult the Requirements documentation for additional advice.
- If all the requirements are met, proceed through the brief questionnaire.
- If you have a separate MySQL database for CiviCRM, then locate "Environment: CiviCRM Database". Click the edit icon and enter the database URL.
- Finally, click "Install CiviCRM".

Run installer via the command-line

CiviCRM has a command-line administration tool, cv, which can perform installation. For details, see command-line installer.

Troubleshooting¶

Review the Troubleshooting page for help with problems you may encounter during the installation.

Post-installation¶

Recommended steps to perform after installing CiviCRM on Drupal.

Review the permissions¶

Drupal will create the /files/ directory (and make it writeable), but only when saving admin/settings. Same holds for /temp directory, and a /uploads/ directory in the CiviCRM module root. On a brand-new Drupal install, this directory may be missing. Even on an existing installation, if file permissions are not set properly, the directory may be missing. If enabling the CiviCRM module generates errors regarding the files directory, you must create it (writeable) manually.

Go to the CiviCRM dashboard to see the CiviCRM menus: https://example.org/civicrm (or https://example.org/index.php?q=civicrm if you don't have Clean URLs enabled)
Go to Administer » User management » Permissions
Verify that the Roles that you want to have access to CiviCRM have the appropriate permissions checked. CiviCRM is installed with a number of fixed permissions (such as "edit contacts" and "administer CiviCRM").

Permissions for the Anonymous Role

Many sites want anonymous visitors to have access to certain CiviCRM functionality. These permissions are enabled during installation for the Anonymous role. You should review them and modify if needed based on your requirements:

access all custom data : If you plan on collecting "custom" data from visitors in standalone forms or as they make a contribution - enable this permission.
access CiviMail subscribe/unsubscribe pages : If you are planning on using CiviMail, enable this permission to allow anonymous users to subscribe and unsubscribe from mailing lists via the web.
access uploaded files : If you plan on allowing visitors to upload or view photos or other files - enable this permission.
make online contributions : If you plan on soliciting online contributions from visitors, enable this permission for the "anonymous" role.
profile listings and forms : If you plan on collecting name and address or other information from visitors, enable this permission for the "anonymous" role.
view event info and register for events : If you plan to use CiviEvent and want to allow un-authenticated visitors to view event information and register for events online - enable these permissions for the "anonymous" role.
view event participants : Enable this permission to allow anonymous users to access participant listing pages for events.

Synchronize the users¶

Once installed, CiviCRM keeps your Drupal Users synchronized with corresponding CiviCRM contact records. The 'rule' is that there will be a matched contact record for each Drupal user record. Conversely, only contacts who are authenticated users of your site will have corresponding Drupal user records.

When CiviCRM is installed on top of an existing Drupal site, a special CiviCRM Administrative feature allows you to automatically create CiviCRM contacts for all existing Drupal users:

Login to your Drupal site with an administrator-level login
Click the CiviCRM link in the main navigation block
If your Drupal site makes use of the db_prefix setting (in settings.php), in the top bar click Administer » System Settings » CMS Database Integration , and update the box for the Drupal Users Table Name so that it includes the prefix.
Click Administer in the menu bar
Click Users and Permissions from the drop-down menu, then select Synchronize Users to Contacts

Review the checklist¶

The Configuration Checklist provides a convenient way to work through the settings that need to be reviewed and configured for a new site. You can link to this checklist from the installation success page and you can visit it at any time from Administer » Administration Console » Configuration Checklist.

Test-drive CiviCRM¶

There should now be a CiviCRM link in your Drupal menu. Click that link and the CiviCRM Menu, Shortcuts, Search and New Individual Blocks should appear. You can now explore CiviCRM end-user features and begin configuring CiviCRM for your site/organization needs.

Addenda¶

TLS for MySQL¶

If your MySQL database is hosted on a different machine than your web server, or if your host requires it, you can use TLS to encrypt the connection between the database and the web server.

Full instructions on installing drupal are out of scope for this guide, but one method is to install into a test database first without MySQL encryption and then move the database to the live server and update settings.php to enable MySQL encryption.

See TLS for MySQL for introductory concepts and the settings for the CiviCRM database. For the Drupal database you have several options for updating settings.php:

The simplest, which doesn't require a client certificate, but doesn't verify the server certificate.

$databases = array (
  'default' =>
  array (
    'default' =>
    array (
      'database' => 'drupal',
      'username' => 'dbuser',
      'password' => 'dbpassword',
      'host' => 'db435.examplehost.com',
      'port' => '',
      'driver' => 'mysql',
      'prefix' => '',
      'pdo' => array(
          PDO::MYSQL_ATTR_SSL_CA => TRUE,
          PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT => FALSE,
      ),
    ),
  ),
);

Verifies the server certificate, and doesn't require a client certificate.

Host name must match certificate name

Note that the DATABASE SERVER certificate would have to have a CN (common name field) that matches exactly the host you are using in $databases['default']['default']['host']. So if the host is db435.examplehost.com, then that must be the name on the SERVER certificate.
```
'pdo' => array(
    // A certificate authority bundle.
    // If you are using a self-signed server certificate in a development
    // or testing environment, then this would be the same as the server
    // certificate.
    PDO::MYSQL_ATTR_SSL_CA => '/path/to/ca.crt',
),
```

Client certificate/key pair (not self-signed), and do not verify the server certificate.

'pdo' => array(
    PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT => FALSE,
    PDO::MYSQL_ATTR_SSL_KEY => '/path/to/your.key',
    PDO::MYSQL_ATTR_SSL_CERT => '/path/to/your.crt',
),

Client certificate/key pair (could be self-signed), and verify the server certificate.

'pdo' => array(
    // The SSL_CA can be the same as your.crt if self-signed, but note
    // that it would also have to be a certificate authority for the
    // server certificate. Self-signed would only be for local
    // development testing.
    PDO::MYSQL_ATTR_SSL_CA => '/path/to/ca.crt',
    PDO::MYSQL_ATTR_SSL_KEY => '/path/to/your.key',
    PDO::MYSQL_ATTR_SSL_CERT => '/path/to/your.crt',
),

Integration modules¶

Webform CiviCRM module

CiviCRM Entity module

Project page on Drupal.org