Config Split: Configuration Management for Drupal Projects
Last updated: March 2026 · Reading time: 7 minutes
Drupal stores configuration in YAML files — a major improvement over earlier versions. But what happens when certain modules should only run on the development environment? Or when the configuration on the live system differs from staging?
Without Config Split, you have to manually compare all configuration files with every deployment. That costs time, is error-prone, and blocks automation. Config Split solves exactly this problem.
How Config Split Works
Config Split works with two concepts:
Blacklist. Configuration elements on the blacklist are exclusively managed by the respective split. They do not exist in the sync directory. Example: the Devel module belongs only on the development environment — so it goes on the Dev split's blacklist.
Greylist. Elements on the greylist remain in the sync directory but can be overridden by the active split. This is useful when a configuration is generally the same but differs slightly on Live — e.g., cache settings or email configuration.
The active split is controlled via settings.local.php. With every deployment, Drupal automatically knows which configuration applies. The result: deployments become deterministic and automatable.
Setting Up Config Split: The Practical Workflow
Step 1: Install the module. Config Split is installed via Composer and enabled. Configuration is done under Configuration > Development > Configuration Split settings.
Step 2: Define splits. A separate split is created for each environment (Dev, Staging, Live). Each split gets its own directory and is activated in settings.local.php.
Step 3: Assign modules. Modules that should only run on specific environments are assigned to the corresponding splits. Devel and Kint go on Dev, performance modules on Live.
Step 4: Export and test. With drush csex, split configurations are exported. A drush cim on each environment should show no unexpected changes.
The initial setup effort is worth it: the team saves time on every deployment and avoids configuration errors that could impact the live site in the worst case.
Your Deployment Workflow Needs an Upgrade?
arocom sets up Config Split for your Drupal platform and automates your deployments. Write to us or start with the Future Check.
Do I need Config Split for every Drupal project?
For professional projects with multiple environments (Dev, Staging, Live), Config Split is standard. For simple setups with only one environment, it is not strictly necessary.
What happens during an upgrade to Drupal 11?
Config Split is compatible with Drupal 11. The configuration structure is preserved during the upgrade. arocom accompanies upgrades and ensures that splits are cleanly migrated.
Can Config Split cause deployment problems?
Only with incorrect setup. If splits are not properly configured, configurations can end up on the wrong environment. That is why clean initial setup and documentation are essential.
Read more
- Installing Drupal modules — Practical guide
- Drupal 11 — The most important innovations
- Drupal Development — Concept, architecture, implementation
Discover a random article
Questions about this topic? We'd love to help.
Drupal Future Check
Checklist: Is your Drupal installation future-proof? 15 checkpoints.
Was this article helpful?