Managing your site's configuration

Last updated on
29 September 2023

Drupal stores site configuration data in a consistent manner, everything from the list of enabled modules, through to content types, taxonomy vocabularies, fields, and views.

Making configuration changes on a live site is not recommended. The system is designed to make it easy to take the live configuration, test changes locally, export them to files, and deploy to production. Your site's configuration can be stored as part of your codebase and integrated with version control.

By default, the "active" configuration is stored in the database ("config" table). This is for performance and security reasons. This is the complete configuration for the entire site at that moment. Configuration can be exported and imported as YAML files, either in its entirety, or a single piece of configuration, using Drush and/or Drupal Console config commands or the Configuration Manager. (See below for more details.)

Exporting and importing configuration changes between a Drupal installation in different environments, such as Development, Staging, and Production, allows you to make and verify your changes with a comfortable distance from your site's live environment.

This allows you to deploy a configuration from one environment to another (as a precaution, Drupal checks the site is the same before importing, by comparing its UUID).

Module and theme configuration files

The default configuration shipped with modules, distributions, and themes is imported into the active configuration store when the extensions are enabled. An extension's default configuration is found in its config/install directory. Again, Drupal only reads from that directory when the extension is installed.

How to import, export, and synchronize

With the Configuration Manager core module, you can import, export, and synchronize site configuration via Manage > Configuration > Development > Configuration synchronization (admin/config/development/configuration). You can review changes on the "Configuration synchronization" page before importing them, but there's no confirmation step if you click the "Import all" button.

Either a single object can be imported or exported using a copy/paste workflow. This is useful if, for example, you wanted to just move a newly created view from one environment to another.

Or the full site configuration can also be dumped as YAML files to a tar.gz file. This only works if you're moving configuration between two copies of the same site (e.g. dev and production), because the site UUIDs must match, from where you exported to where you're importing.

After synchronization is complete, all changes will be applied, such as enabling new modules, fields or content types. In short, all configuration changes made on the development site should now be live on production.

To directly edit site config entities, you can use drush config-edit or drupal config:edit, or "Config editor" from the Devel module.

Drupal Site UUID

Each Drupal site gets a unique UUID, generated on install.

This UUID is used to match configuration exports to the correct site.

In order for config import to work, the exported config files must contain a matching Site UUID.

If your exported files do not match, you can change your site's UUID using Drupal Configuration API.

To update your exported files with a different UUID, simply set the UUID and run the export again.

How to get and set a site's UUID

The Drupal Site UUID is stored as the configuration item system.site:uuid

You can set it with drush or in settings.php using $config overrides.

Override Site UUID using settings.php
 

To override the site's UUID, you can put the following snippet into your settings.php file:

$config['system.site']['uuid'] = '1234567890';

Using Drush

drush cget system.site uuid

drush cset system.site uuid 1234567890

Using Drupal Console

drupal debug:config system.site

More synchronization workflow documentation

Do's and Don'ts

DO'S

It's strongly recommended that you do a database-dump before each synchronization of the staging and the active directory. The database-dump "could save your life" on a potentially needed rollback-strategy.

DON'TS

Don't try to change the active configuration on your site by changing files in a module's config/install directory. This will NOT work, because Drupal only reads from that directory when the module is installed.

More Information

If you're looking for more in-depth information about the Configuration Management system in Drupal 8 or higher, you can check the handbook pages for Configuration API.

Help improve this page

Page status: No known problems

You can: