Export‑Import with Config Split: A Practical Guide to Drupal Configuration Management

Why Configuration Management Matters

When you move a Drupal site from development to staging to production, you need a reliable way to transfer every setting that lives in the database. Drupal’s Config Management system turns those settings into YAML files that can be version‑controlled, diffed, and re‑applied on any environment. The Config Split module adds a layer of conditional inclusion so that environment‑specific overrides (like a dev‑only block or a staging SMTP server) stay out of the way on other sites.

What You’ll Do

The article walks through the exact steps to:

• Export configuration to a sync directory.
• Create a Config Split that disables a block in dev.
• Import the configuration on a fresh site.
• Verify the import succeeded and the split behaved as expected.

Step 1: Prepare the Sync Directory

Drupal ships a default sync folder in config/sync. Add it to your project’s repository and commit the empty folder if you use a bare repo. Make sure the directory is writable by the web server during exports.

Step 2: Export Current Configuration

Run the Drush command from the site root (or use the UI “Configuration → Development → Configuration synchronization”).

# Run as the user that owns the Drupal files
$ drush config:export

After export, you’ll see a file like node.type.article.yml in config/sync. The YAML contains all properties of the article content type, including its display settings.

Step 3: Create a Config Split for Development

Install the config_split module if it isn’t already. Then add a split definition in config/split/config_split.settings.yml:

dev:
  status: true
  label: "Development split"
  description: "Exclude dev‑only blocks and settings."
  include:
    - core
    - node
  exclude:
    - block.block.example_block

The exclude list tells Config Split to omit block.block.example_block from the exported files when the dev split is active. To activate the split, set the environment variable CONFIG_SPLIT_ACTIVE=dev in settings.php:

$settings['config_split']['active'] = ['dev'];

Now, when you export again, the block file will be missing from config/sync on the dev instance.

Step 4: Import on a Fresh Site

On a clean test or production site, run:

# Import all exported configuration
$ drush config:import

The import is atomic: if any entity fails (e.g., a YAML syntax error), the whole operation rolls back. After a successful import, run drush config:status to confirm no pending changes remain.

Step 5: Verify the Split Effect

On the dev instance, the excluded block should be invisible. On production, it should remain visible. Use the UI or drush block:list to confirm the block’s status. If you need to test only the article content type, run:

# Import just the article type
$ drush config:import --partial node.type.article

After the partial import, run drush config:status node.type.article to ensure no pending changes for that entity.

Common Pitfalls and How to Avoid Them

• Missing config_export_modules – Custom modules that create configuration entities must list their keys in my_module.info.yml under config_export_modules. Otherwise, UI changes won’t appear in the sync folder.
• YAML syntax errors – A single bad line will abort the entire import. Run drush config:validate or a YAML linter before importing.
• Overriding in settings.php – Values in $settings['config_overrides'] win over imported values. Use this sparingly and document overrides in version control.
• Config Split mis‑names – If the split name in settings.php doesn’t match the key in config_split.settings.yml, the split will be ignored. Verify with drush config:split:list.
• Running config:import on production without review – Always diff the changes first. The UI diff page shows added, changed, and removed entities.

Limitations of the System

• Only configuration entities are exported; files, user accounts, and custom database tables are not part of Config Management.
• Atomicity is limited to configuration entities – if a module’s installation requires database changes outside the config system, those changes are not rolled back automatically.
• Large sites may generate thousands of YAML files; ensure your VCS can handle the volume.
• Config Split is a best‑effort override; if a split excludes an entity that other split files depend on, you may end up with missing routes or blocks.

Practical Checklists

• Before Export: Verify config/sync is writable and under version control.
• After Export: Run git status to see new or updated YAML files.
• Before Import: Use drush config:status to see pending changes.
• After Import: Run drush config:status again; no pending changes should appear.
• Test critical paths (login, content creation) to confirm the site behaves as expected.

Conclusion

Drupal’s Config Management, combined with Config Split, gives you a repeatable, version‑controlled deployment flow. Export the entire site, apply environment‑specific overrides, and import atomically on any target. By following the steps above and guarding against the common pitfalls, you can move configuration safely from dev to prod without surprises.