Creating a new instance of an existing site

- UPDATE 2/2/2018 -
See: Using the Configuration Installer with Lightning

Throughout the development and support lifecycle of a site, it is often necessary to install a fresh version of your application in a new environment with all of the existing site's configuration. For example, a new developer might need to set up their environment for the first time or your CI system might want a fresh install for tests. Basically:

As a user I want to be able to install Drupal from a package of configuration that is maintained in git.

Existing solution (pre Drupal 8.4.x): Drush --config-dir option

Installing a site from existing config is not as easy as going through the install process and then importing config though because the fresh install will have a different site UUID than the existing app and Drupal won't allow you to import configuration on sites with different UUIDs. To work around this, Drush introduced the --config-dir option to the site-install command which imported the configuration during install and magically worked around the UUID issue.

That workaround did have other issues including the fact that base fields defined in module or profile config would end up with conflicting UUIDs. But critically, Drush 9 only supports the --config-dir option when installing the Minimal profile - and Drush 8 isn't compatible with Drupal 8.4.x. So we need a new solution.

Investigated approaches

The Drush maintainers have suggested using the Config Installer profile. We tested it and works great, but:

  1. It's undocumented.
  2. It won't work if you're using Lightning as a Base Profile, which we recommend.

In theory, you could also manually set your site's UUID after install and then import your config, but this is sloppy and is an abuse of UUIDs. It also wouldn't solve the problems with base fields ending up with conflicting UUIDs.

Solution (Drupal 8.4.x): Another core patch

Enter the following issue: [#2788777] Allow a profile to be installed from existing config. The patch in #91 allows you to add a simple boolean to your sub-profile's info file that will automatically install your site with config from the config sync directory defined in your settings.php file. The end result is that no matter how you install your site (via Drush, the UI, or Drupal Console), your existing config will also be imported.

The only problem is that the scope of the issue is still being debated. As a result, Lightning can't bring the patch in just yet. But we will as soon as the issue is RTBC or we get further clarity about the scope. In the meantime, you can bring the patch in yourself.



  • Your site's config sync directory is located in a VCS tracked directory (e.g. "../config/sync").
  • You use a sub-profile.
  1. Apply the patch #91 from issue #2788777 to drupal/core, in your root composer.json file:
    "patches": {
        "drupal/core": {
            "Allow a profile to be installed from existing config":
  2. Add the boolean flag to your sub-profile's info file
    config_sync: true


The result will be that each time you install your site, all of your existing configuration will also be imported.

If you are not using a sub-profile, you can simply use the Config Installer profile mentioned above.

  1. Add the Config Installer profile to your codebase
  2. During installation select Config Installer as the profile
  3. Point Config Installer to your exported config directory (the resulting installation profile will still be Lightning even though you selected Config Installer)

If you're using BLT in your project (recommended), a lot of the configuration setup is already handled for you. See BLT's notes about updating to Drupal 8.4.x.

Powered by Drupal Lightning