Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 37 ยท Concepts and Installation

Configuration Management Basics

Learn Drupal's configuration management: active versus sync storage, drush config:export and config:import, UUIDs, config split basics and a safe deployment workflow.

You build a content type on your laptop. Now you need the same content type on the staging server and later in production. You could click it together three times and hope you remembered every setting. Drupal offers a better way: configuration management. Site-building decisions are stored as structured data that you export to YAML files, commit to Git and import elsewhere.

This is one of Drupal's most valuable features for teams, and it is the reason "configuration" and "content" are kept separate in the model you met in Entities, Bundles and Fields.

What counts as configuration

Configuration is anything that defines how the site works rather than the data it holds:

  • Content types, fields, form and view display settings.
  • Taxonomy vocabularies, roles and permissions.
  • Views, menus, block placements, text formats, image styles.
  • Settings of modules (site name, performance, account settings).
  • The list of enabled modules and themes (core.extension).

It does not include nodes, users, comments, files or taxonomy terms: those are content.

Active and sync storage

Drupal keeps configuration in two places:

  • Active configuration: what the running site uses, stored in the database (the config table).
  • Sync directory: YAML files on disk, usually config/sync, which you version with Git.

Export copies active to files. Import copies files into active.

flowchart LR
    A["Active config (database)"] -- "drush config:export" --> B["config/sync (YAML files)"]
    B -- "Git commit and deploy" --> C["Other environment: config/sync"]
    C -- "drush config:import" --> D["Other environment: active config"]

Configuration travels through files; content stays in each database.

The workflow

On your local site, after changing something in the UI:

Terminal
vendor/bin/drush config:export -y
git add config/sync
git commit -m "Add event content type"

On the target environment, after deploying the code:

Terminal
vendor/bin/drush updatedb -y
vendor/bin/drush config:import -y
vendor/bin/drush cache:rebuild

Before importing, drush config:status shows differences, and drush config:import prints a summary of what will change.

A look at an exported file

Configuration YAML files are named module.type.id.yml. For example, a content type called Event is stored as node.type.event.yml:

YAML
uuid: 8a2d6f2e-3c6f-4a5b-9b38-1f4a9d0e7c11
langcode: en
status: true
dependencies: {  }
name: Event
type: event
description: 'A scheduled event with a date and place.'
help: ''
new_revision: true
preview_mode: 1
display_submitted: false

Each file has a UUID. For configuration entities, the UUID lets Drupal match a file to an existing item when importing. This leads to an important rule: a site and its deployments must share a baseline. Import only works between sites created from the same site UUID, which is why you install production from your project's configuration instead of installing a fresh, unrelated site.

Field definitions are split into storage and instance files: field.storage.node.field_date.yml and field.field.node.event.field_date.yml. Display settings are in files like core.entity_view_display.node.event.default.yml.

Dependencies

A config file lists what it depends on (a module, a theme, another config item). Drupal imports items in dependency order and refuses to import something whose module is not enabled. That is why core.extension.yml, the list of enabled modules, is part of the sync directory.

Different config per environment

Sometimes production needs different settings, for example a disabled development module or a different API key. There are two approaches:

  • Config overrides in settings.php: $config['system.site']['name'] = 'Staging'; These are not exported.
  • Config Split (a contributed module): maintains extra sync directories that apply only to chosen environments.

Never keep secrets such as API keys in exported config. Put them in environment variables or settings.php on the server.

Merge conflicts

Because exports are text, teammates may edit the same file. Resolve conflicts in Git as usual, then import and re-export to confirm things are consistent. Commit often, keep changes small, and export in the same commit as the code that needs it.

A config diff you can run

The stand-in compares "active" and "sync" configuration objects and prints what an import would do, like drush config:status. It illustrates the logic; real Drupal compares YAML data per item in a similar way.

JS Stand-in: what would an import change?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Note the delete line: importing makes active configuration match the files exactly, so anything missing from the files is removed. That is why you export before you import on a site that has had hand changes.

An export and import round trip

This second stand-in simulates the full cycle: change in the "UI", export to files, deploy, import on another site. It confirms that the two environments end up identical.

JS Stand-in: export, deploy and import

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Practical rules

  1. Make changes locally, export, commit. Do not edit config on production.
  2. Deploy code first, then run updatedb, then config:import.
  3. Review the exported diff; unexpected changes in unrelated files are a warning sign.
  4. Keep content out of config; use migrations or default content for starter data.
  5. Treat the sync directory like code: review it in pull requests.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Where does Drupal keep the active configuration?

    Active configuration lives in the database; the sync directory holds exported YAML copies.
  2. 2. Which command copies active configuration to files?

    config:export writes the active config to the sync directory.
  3. 3. Which item is NOT configuration?

    Articles are content, stored in the database and not exported with configuration.
  4. 4. What is the correct deployment order on the target site?

    Code must be present first; database updates run before configuration import, followed by a cache rebuild.
  5. 5. Where should API secrets live?

    Secrets should not be committed; keep them in the environment.

Summary

  • Configuration (content types, Views, roles, settings) can be exported to YAML and imported elsewhere.
  • Active config is in the database; the sync directory holds the files you commit.
  • Deploy code, run updatedb, then config:import, then rebuild caches.
  • Keep secrets and content out of config; use overrides or Config Split for per-environment differences.

Next: Content Types and Fields