This documentation refers to an older version of CiviCRM (3.4 / 4.0). View latest version.

Skip to end of metadata
Go to start of metadata
This page refers to CiviCRM 3.4 and 4.0, current STABLE version.

Documentation Search

CiviCRM 3.4 and 4.0 Documentation

Support and Participation

Developer Resources

CiviCRM books!

Make sure to check out the FLOSS Manual Understanding CiviCRM as well! You can also support this project by ordering a hard copy.

Or support us by buying an eBook or hard copy of Using CiviCRM from Packt Publishing.

A number of settings stored in CiviCRM's database relate to the physical location in the server file system and the URL path. When you move an existing CiviCRM installation to a new server (or a new location on the same server) - these settings usually need to be changed. This documentation covers the general steps.

These instructions have been rewritten based on my recent migration experience and are also informed by this blog post: The overall process I am suggesting is to install a fresh working copy of CiviCRM on your new server. Next copy any custom code then move the majority of your database from the old server, ignoring domain and cache tables. This leaves the good working domain data in place on your new server.

Some sites may have been advised to create a file /path/to/civicrm/settings_location.php, which hardcodes the path to the site configuration directory. This is used to work around issues with deducing the site configuration path. If your site has such a file, it may require updating along with the hardcoded paths in civicrm.settings.php

If you are using Joomla, Akeeba backup is a handy plugin to create complete backups of your site, including CiviCRM. It does not only copy your database but all your files too. Configure Akeeba to ignore tables, table content and files as described below. Such a backup can be restored easily and completely using its complementary Kickstart script on any site, not just your original site, because it contains all restoration scripts necessary to get you up and running.
If you are transfering to a new host some paths and URLs probably have changed so you must update:
1) all URLs that points to your old site in both the civicrm.settings.php (in .../administrator/components/com_civicrm and .../components/com_civicrm) as described below
2) all database connection strings in both the civicrm.settings.php (in .../administrator/components/com_civicrm and .../components/com_civicrm) as described below
3) all file paths to the installation in both the civicrm.settings.php files *as well as* the civicrm.config.php file which resides in <joomla-root>/administrator/components/com_civicrm/civicrm
One thing that tricked me was that while I tried (and failed) to run the site with erroneous settings, CiviCRM created cached files in .../media/civicrm. But once I removed them the site worked fine without updateConfigBackend and rebuild the menus as described below (but I suppose you can do them if needed).

  1. Disable but do not uninstall CiviCRM in your CMS.
  2. Copy the codebase files or execute a fresh install of your CMS to the new location.
    1. If you decide to do a fresh install, you will also need to recreate your (non-CiviCRM) installed module base.
    2. Do not copy your civicrm.settings.php from the old server, rather, install a clean copy of CiviCRM: Installation and Upgrades
  3. If you decide not to do a fresh install, be sure to review the file paths in civicrm.settings.php, such as civicrm_root and CIVICRM_TEMPLATE_COMPILEDIR
  4. Copy your databases.
    1. Drupal: Consider Backup and Migrate Module to migrate the Drupal side. If your CiviCRM data is in a seperate database, Backup and Migrate can also backup your CiviCRM data but it cannot ignore tables. Ignored tables skirts alot of issues and this guide assumes that you are ignoring at least the civicrm_domain table.
    2. Command Line: Substitute mysql_username, cms_db_name and dump_file_name_of_your_choice with appropriate values.
      Multi-lingual Installs

      Do not ignore the civicrm_domain table if your setup is multi-lingual as this is the table where CiviCRM stores which languages are enabled.

      mySQL Dump for Drupal
      mySQL Dump for Joomla
  5. Load your database(s) into to the new MySQL server
    1. Drupal: Again consider Backup and Migrate Module to migrate the Drupal side.
    2. Command Line: Substitute mysql_username, cms_db_name and dump_file_name_of_your_choice with appropriate values.
      Load mySQL Dump for Drupal
      Load mySQL Dump for Joomla
  6. Delete files with cached settings
    • Drupal:
      • <drupal-root>/sites/default/files/civicrm/templates_c/* (cached versions of Smarty templates that will be rebuilt)
    • Joomla:
      • <joomla-root>/media/civicrm/templates_c/*
  7. Login to Drupal or to Joomla Administrator
  8. Re-enable the CiviCRM module.
  9. Enter the following URL in your browser to review and update directory paths and base URLs:
    • Drupal sites: http://<drupal_site>/index.php?q=civicrm/admin/setting/updateConfigBackend&reset=1
    • Joomla 1.5 sites: http://<joomla_site>/administrator/index2.php?option=com_civicrm&task=civicrm/admin/setting/updateConfigBackend&reset=1
    • Joomla 1.6 sites: http://<joomla_site>/administrator/index.php?option=com_civicrm&task=civicrm/admin/setting/updateConfigBackend&reset=1
  10. Review the recommended modified paths in the form - they should reflect the new Base Directory, Base URL, and Site name for CiviCRM.

    Base Directory - For Drupal installs, this is the absolute path to the location of the 'files' directory. For Joomla installs this is the absolute path to the location of the 'media' directory.
    Base URL - This is your Drupal or Joomla site URL (e.g.
    Site Name - The name of your Drupal sites subdirectory, starting from the docroot, and including an initial /, e.g. /sites/

    1. If these values do NOT look correct, then recheck the changes you made to civicrm.settings.php.  If everything looks right in your civicrm.settings.php file, you may want to follow the directions for setting config_backend to null in the Troubleshooting section (below).
    2. Otherwise click Save.
  11. Rebuild the menus. The menu links in the civicrm_menu table contain full URL links and need to be updated with the new domain.
    • Drupal sites: http://<drupal_site>/index.php?q=civicrm/menu/rebuild&reset=1
    • Joomla 1.5 sites: http://<joomla_site>/administrator/index2.php?option=com_civicrm&task=civicrm/menu/rebuild&reset=1
    • Joomla 1.6 sites: http://<joomla_site>/administrator/index.php?option=com_civicrm&task=civicrm/menu/rebuild&reset=1
  12. Joomla 1.6/1.7 - Edit the path in /administrator/components/com_civicrm/civicrm/civicrm.config.php which may still use your old location.
  13. If you made any non-CiviCRM changes to your site (e.g. exposed profiles on the Drupal nav bar) don't forget to fix (e.g. for Drupal: Administer >> Site building >> Menus >> Navigation).

    Your 'files' directory is typically outside of your CiviCRM install directory. The below step is important for proper operation on a new site.

  14. Go to Administer CiviCRM > Configure > Global Settings. If you are using custom templates or PHP then you'll need to click on Directories to update the directory locations for these (/civicrm/admin/setting/path?reset=1). You should click on Resource URLs to ensure these are correct.

As a result of your migration, many of your site's other configuration settings have been reset, for instance Available Countries in "Localization" and reCaptcha keys. Page through the Configuration Checklist at Administer CiviCRM > Configuration Checklist to be sure that all your settings are once again set to their correct values.

Your site should now be properly configured for its new location.


Only the front page of your site can be displayed - Drupal

If you are using drupal on Ubuntu, you may find that your site looks to be working until you click on a link or go to any other url than the front page. This can be caused by the default setting for the Apache mod-rewrite module. If you can load url's like, "http://<yoursite>/index.php?q=/civicrm/admin/setting", but not "http://<yoursite>/civicrm/admin/setting, then this is likely the cause.

Use the following article, or many others on the web to enable mod_rewrite. --

Only the front page of your site can be displayed - Joomla

I just had an issue at step 6 above getting to the page where the directories can be updated. There was an error with Joomla 1.7 / CiviCRM 4.0.5 on a site that had been upgraded a few times already: Failed opening required 'CRM/Core/Config.php. I solved this by manually editting [DOCROOT]/administrator/components/com_civicrm/civicrm.settings.php and [DOCROOT]/components/com_civicrm/civicrm.settings.php to replace incorrect values for $civicrm_root, CIVICRM_TEMPLATE_COMPILEDIR, and CIVICRM_UF_BASEURL (the latter since I was using a different URL on my local dev machine).

Unable to update Config Backend

This process should avoid this error, however if after entering the "updateConfigBackend" URL you may get an error suggesting you need to set the Config_Backend column to NULL. Please execute the following sql in your database (using mysql shell or PHPMyAdmin)

This field contains many other useful CiviCRM configuration settings, such as what components are enabled, your mailserver setting, what countries are enabled, etc.  You should only NULL this as a last resort.

  1. this was not enough for me. I entered a path that was incorrect in the php and extension options. I had to go into the database and find the path the error message noted it was trying to make and replace it in civicrm_option_value. To find it I ran

Then I did an update to the two rows it found.
In this case it was the row labeled Custom PHP and Custom Extensions.

Table 'db_name.civicrm_option_value_en_us' doesn't exist

The error occurs on multi-lingual migrations when the source server is not case sensitive but the destination server is. To correct this error, edit the database dump in a text editor and globally find and replace your language codes to the proper case. The second pair of letters should be upper case, as in en_US.

  • None