Your Complete Introduction to Drupal 8 Configuration Management

| Drupal
The Complete Introduction to Drupal 8 Configuration Management

A lot of OSTraining members have started to experiment with Drupal 8.

Some of the features are really well documented and are easy to use. Some others require more explanation. One such feature is Configuration Management. The aim of this feature is to make it easier to use a development-live site workflow in Drupal 8.

Here is our introduction to Configuration Management in Drupal 8 ... 

An introduction to Configuration Management in Drupal 8

In Drupal 7, users who struggled to set up an effective system of moving from development to live sites. If you changed your settings on a development site, it was often difficult to move those to your live site.

The Configuration Management improvements in Drupal 8 are designed to make that much easier. Configuration Management was one of several major initiatives for Drupal 8 and was led by the team at

In Drupal 8, many configuration settings can now be stored in files, rather than the database. The idea is that if configuration settings can be put into files, that should make it easier to move the settings between development and lives sites. Settings can also be version controlled, if they're in files.

Matthew Tift, who helped spearhead the initiative, gave this introduction to Configuration Management at DrupalCon Austin:

How Configuration Management work

First, you will find configuration files inside the /config/install/ directory. These settings will create the configuration when a module is first installed. However, don't try to update a module using these files. Drupal will only read from that directory when the module is installed.

The data is stored in YAML files, which use the .yml suffix:

Drupal 8 Configuration management YML files

Second, when you install Drupal 8, there will be two randomly-named directories inside the public files folder. Normally that will mean the directory for sync files is in /sites/default/files/. It is possible to change this location if you follow these instructions.

Drupal 8 Configuration management folders

One of these directories will contain a subdirectory called /sync/. This is where your files will be stored when you move configuration between sites:

Drupal 8 Configuration management sync folder

The other directory will contain two subdirectories, /active/ and /staging/. These folders are here to illustrate a very basic configuration workflow: moving between an active and a staging site.

Alex Tkachev says:

The active directory is supposed to keep currently active configuration. I said “is supposed” because by default this directory is empty, active configuration is stored in the database. It is made this way for performance and security reasons. However, you can force configuration storage to use the file system with the Configuration Tools module. The staging directory is the place from where the configuration is imported/synchronized. It’s also empty until configuration will be exported/imported.
Drupal 8 Configuration active and staging folder

In the quote above, Alex mentioned that configuration is not always stored in files. So if it's not in files, where are the configuration settings?

Unless you are importing or exporting configuration, it will normally be stored in the config table in the Drupal 8 database:

Drupal 8 Configuration database tables

Configuration Management in the Drupal 8 admin area

There is a user interface for Configuration management. You can find this by going to Configuration > Configuration synchronization.

Here's what the interface looks like:

Drupal 8 Configuration management admin interface

You have several choices:

  • Synchronize: Here you can actually sync changes from a file that you have imported
  • Import: This allows you to import sync changes from other sites.
  • Export: This gives you two choices: "Full archive" or "Single item".
Drupal 8 Configuration management export

If you do a "Full archive" export, and then import it to a new site, your /sync/ directory will fill up with .yml files:

Drupal 8 Configuration management files in sync folder

The "Single item" option allows you to export the settings for individual items on your site. Here's an example export of a single field:

Drupal 8 Configuration management single item export

These user interface settings for Configuration Management are very promising, but they still have significant limitations:

  • Single items can not be exported into a file. You will have to copy-and-paste the details.
  • You can't select multiple items at once. So you can't select a content type and multiple fields.

To be honest, this interface feels half-finished and I expect improvements may come in Drupal 8 or later releases. So, most people are likely to continue to use the Features module for more advanced configuration management.

How to use Configuration Management

In its current form, the main purpose is to allow you to take a copy of live site and create a development site.

Here's the explanation from

The goal of the configuration system in Drupal 8 is to make taking a copy of the site configuration easy to set up a development site where you make changes. Then importing those changes on the live site is also made simple.

So, in practice, the "Full archive" will be the only option that most people use. again:

The full export feature is a lot more powerful. You can download an archive of all the active configuration files with this feature. This can be used to import on a development site (given the two sites are copies of each other) to import, synchronize, make changes, package up again and import and synchronize back on the live site as well.

If you do want to use the Configuration Management to recreate a live site and as a development site, here's the 5-step process recommended by

  1. Install Drupal 8. We will call this site "Live."
  2. Make a copy of this site. We'll call this "Development". Make the copy by using the same source code, the files directory and a database dump of the Live site imported on Development.
  3. Using the Configuration Management interface, export the full Development site configuration. This will create a compressed file called config.tar.gz.
  4. On the Live site, use the Configuration Management interface to navigate to and import the compressed file.
  5. After upload, review the changes (as in the image below) and click the "Import all" button.
Drupal 8 Configuration management review changes

The Universally Unique Identifier

One important thing to understand about configuration is the UUID or the Universally Unique Identifier.

This is a concept that's used in many different situations: even your phone probably has a UUID. This concept has been around in Drupal for some time. In Drupal 6 and 7, there was a module called UUID.

What the UUID often does is provide unique keys that identify certain parts of your site. Here are some UUIDs in the key_value table in a Drupal 8 database. The UUIDs shown below are the unique keys for menus and content types. The keys looks like this uuid:03782c1d-b2ae-47be-8f00-b8fe44d8a334.

Drupal 8 Configuration management UUIDs

So, here's where the UUID's become important for configuration management. You can not important configuration settings unless both the exporting and importing sites have exactly the same UUID.

In other words, configuration management only works if the sites are exact clones.

If you try to import to a site that is not an exact clone, you will get this message:

Drupal 8 Configuration management synchronize error

So, as you can imagine, this does restrict the usefulness of the core configuration management interface. You cannot move configuration settings between different sites.

This video gives an overview of UUIDs:

About the author

Steve is the founder of OSTraining. Originally from the UK, he now lives in Sarasota in the USA. Steve's work straddles the line between teaching and web development.