Configuration management

The Drupal practice of deploying settings such as content types, fields and views through files and Drush, instead of repeating them by hand.

Learn DrupalDrupal glossary
Edited by Founder and CEO, DXPR Last updated

Configuration management is the way a Drupal team keeps a site's settings under control across environments. You make a change on a development copy, export it as YAML files, store the files in Git and import them on the live site. Nobody redoes the change by hand, and the live site never drifts from what the team tested.

How it works in Drupal 11

Drupal keeps the live settings, called the active configuration, in the database. Exporting writes them to the sync directory, one YAML file per item. By default Drupal creates that directory under a randomly named folder in the public files path. Setting $settings['config_sync_directory'] in settings.php moves it, for example to a folder outside the web root that sits in your Git repository.

Two tools do the work. The core Configuration Manager module (config) provides the screens under Administration › Configuration › Development › Configuration synchronization, and the standard installation profile enables it. Drush provides the commands config:export, config:import and config:status, with the short forms cex, cim and cst. Import lists the pending changes and asks you to confirm.

Import has one hard rule. The files must come from the same site, because Drupal compares the site UUID in the files with the one in the database. If they differ, the Synchronize screen refuses and says the configuration originates from a different site. Create the development copy by cloning the live site, or install a new site from the exported configuration; an unrelated fresh install will not import.

Example

A developer adds a field to a content type on a local copy, then runs:

drush config:export
        git add config/sync
        git commit -m "Add summary field to case study"

After the code reaches the live server, the deploy step runs drush config:status to see what differs, then drush config:import and confirms the list. The field now exists on the live site, with the same settings that were tested.

Options for real projects

  • Excluded modules. Core reads the config_exclude_modules setting. Modules named there, such as development helpers, are left out of the export, and an import does not uninstall them.
  • Config Split. This contributed module keeps extra sets of configuration for specific environments. Version 2.0.2 (February 2025) lists Drupal 11 support and is covered by the Drupal Security Team (checked 26 October 2026).
  • Config Read-only mode. With $settings['config_readonly'] = TRUE;, this contributed module blocks configuration changes made in the admin interface, so the live site stays read-only. It lists Drupal 11 support.

Common mistakes

  • Changing settings on the live site. Drupal.org advises against it. A later import can overwrite the change, and Drupal warns that such changes may be lost.
  • Exporting into a folder you care about. The Drush workflow guide says an export deletes the current contents of the sync directory. Commit or inspect it first.
  • Skipping the backup. The Drupal.org guide strongly recommends a database dump before each synchronization.
  • Not committing the files. Exported YAML that stays on one laptop is not deployable. Put it in version control with the code.

For marketing and content teams

Creating a content type, a vocabulary or a view is a configuration change, so ask your developers to deploy it rather than rebuilding it live. Editing a page is content and needs none of this. If a new field "exists locally but not on the site," the configuration has not been imported yet.

Sources

Questions about Configuration management

Configuration is the data: your content types, fields, vocabularies and views. Configuration management is the process around it: building changes on a development copy, exporting them to files, and importing them on the live site. See configuration for the data itself.

No. Configuration covers settings such as the site name, content types, fields and views. Articles, pages and uploaded files are content and travel by other means, such as a database copy. A configuration import never carries your editors' work between sites.

Core defines three: Synchronize configuration, Export configuration and Import configuration. All three are marked as restricted, so grant them only to administrators who deploy changes.

Related terms

All Drupal terms from A to Z