Last updated April 5, 2018

The configuration system provides a way to move your site's configuration from one instance of the site to another (for example, from "dev" to "live"), but it is very unopinionated about what workflow you should use to accomplish this -- or even whether you should use the system at all. In this tutorial, we'll look at 3 common scenarios and, where applicable, suggest a sensible configuration management workflow that may clarify how you should (or should not) manage your site's configuration.


Decide on an appropriate configuration management workflow that fits your use case.


This tutorial assumes you are familiar with local development with Drupal. If you need a refresher, consult the following resources:

Scenario 1: Configuration not managed at all

For all of the well-earned hype about configuration management in Drupal, it might not be something you'll end up using in your site administration. You might not manage configuration at all if your site requires only basic management, meaning:

  • You are the one and only administrator and developer of the site, with the possible exception of the themer.
  • It's a low-traffic site.
  • There's no e-commerce-related configuration.
  • Your site is mostly Drupal "out-of-the-box" (except for maybe the theme).
  • You consider the configurations you plan to do "low risk."
  • Your primary concern is keeping Drupal core and contributed modules up-to-date with new releases.
  • You're not making regular configuration changes to your site.

If this describes your scenario, you probably don't need to manage your site's configuration. However, you should still take a look at the next scenario and learn to export configuration to files because invariably you will end up editing configuration on the live site at some point in the future.

Finally, even if you don't use the configuration management system, you should still plan to make regular scheduled backups of your site, database, and files.

Scenario 2: Configuration sync directory in use, but sometimes configuration on the live site is edited

In our second scenario, you have moved exported configuration files to the live site into a config sync directory and you have made (or need to make) some configuration changes on the live site.

Plus, any of the following applies:

  • You have a "dev" instance of your Drupal site that isn't in sync with the "live" site configuration and you want to get it in sync.
  • You have some changes you've made on a dev instance that you want to deploy to the live site and you want to avoid blowing away changes you or someone else has made on the live site.
  • It's been awhile and you're not sure if you've made changes to configuration on the live site instance.

If any of the statements above ring true, you'll want to set up a new workflow in which: - You set up a local development instance, make and test your configuration changes there, export your configuration to files in your config sync directory, and finally use command-line tools like Git and Drush to deploy and import changes to the live site.

Recommended workflow:

  1. If you don't have a clone of your live site, make one for your local environment (a "dev" instance). (Learn how to clone your Drupal site with command-line tools or with GUI tools.)
  2. Export active configuration on the live site to files and commit the file changes using version control, commit and push to your remote Git repository. (Learn how to Manage Configuration with Command-Line Tools or how to use the Configuration Manager to export configuration to files.)
  3. On the "dev" site, pull changes from the Git remote repository. This will pull in the exported configuration files from the live site.
  4. Still on dev, run drush config-import to import new or changed configuration from the configuration files into your dev site instance's active configuration (the database, by default).
  5. On the live site instance, stop making changes for the time being. (Communicate this to anyone else with administrative or Git push privileges to the live site.)
  6. On dev, make and test your configuration changes.
  7. On dev, export configuration to files (drush config-export)
  8. On dev, commit config file changes and new config files to version control, and push to the site's Git remote repository.
  9. On the live site, pull changes from the Git remote repository.
  10. On the live site, import configuration (drush config-import) from files into active configuration (the database, by default)
  11. Verify the configuration changes on the live site. Not seeing the changes? Rebuild or clear cache (drush cache-rebuild) and/or run drush updatedb (database update).

Scenario 3: Configuration changes are always made and tested on non-production instance(s) and then deployed to live.

In this scenario, you want to set up a strict workflow policy that can be used across your team in order to ensure consistent, successful deployments of configuration changes.

  1. Create a clone of your Drupal site for your local environment. (Clone the most up-to-date "canonical" version; this could be the live site or a dev site yet to be launched.) Cloning means you now have an exact copy of your Drupal site's codebase, files, and database.
  2. Set up a local.settings.php and create any necessary configuration overrides for your local environment.
  3. Pull in the latest changes from the site's Git remote repository and import any changes into your site's active configuration.
  4. On your local instance, make your configuration changes.
  5. Export configuration using Drush.
  6. Examine the diff using Git to verify your configuration changes were captured in file(s) as expected.
  7. Commit new and modified configuration files to version control using Git.
  8. Push changes to the Git remote repository.
  9. (Optional: Automate steps 10 through 13)
  10. On the live site, pull from the Git remote repository
  11. Import configuration using Drush (drush config-import)
  12. Rebuild the cache (drush cache-rebuild)
  13. (Optional, but doesn't hurt) Update the database (drush updatedb)

If you're the one and only site admin and developer...

You might find it more convenient to use a combination of the Configuration Manager UI and command-line tools Drush and Git, so learn how to use both GUI and command-line tools to manage and move your site's configuration between instances.

Periodically, you might find it necessary to edit configuration on the live site, so learn how to get your local instance back in sync with your live site, and be cautious not to blow away changes on your live site when you're pulling in and importing new changes from dev. Reference scenario "2" above for how to accomplish this.

If you're working on a team...

  • Develop and document the workflow your team will use.
  • Know your site owners and stakeholders. Will they edit configuration on the live site just because they can? Consider installing Configuration Read-Only Mode to prevent this, but note that this contributed module is not currently covered by Drupal's security advisory policy.
  • Decide on the tools and methodologies your team will use.
  • Test processes and automate where possible.
  • Investigate Drupal contributed space for configuration-related modules that might solve particular issues or use-cases your team is facing. New configuration management modules and workflows are being developed all the time. Keep an eye on Drupal Planet for blog posts from agencies and individual developers who are sharing their knowledge and experiences with configuration management. Also, bookmark our Manage Configuration and Workflows topic page for curated resources on this subject.

Configuration Sync Workflows


In this tutorial, we laid out several common development/site administration scenarios and how you might or might not want to manage your site's configuration and suggested a recommended configuration management workflow for each scenario.

Further your understanding

Now that you have a high-level understanding of the configuration management workflow you will use, learn the details of how to execute this workflow successfully:

Additional resources