Drupal Config Management Cheatsheet

What is Drupal Config Management?

Drupal stores all site configuration (fields, content types, views, image styles, roles, etc.) in the database. The configuration management system lets you export that config to YAML files, track them in git, and import them on other environments.

This means your site structure is version-controlled and deployable.

---

The config/sync directory

YAML files live in config/sync (or wherever your settings.php points to).

// web/sites/default/settings.php
$settings['config_sync_directory'] = '../config/sync';

These files are not live — they are a source of truth that must be explicitly imported into the database.

---

YAML filename anatomy

field.field.node.pro_occupations.field_anz.yml
│     │     │    │                │
│     │     │    │                └─ field machine name
│     │     │    └─ bundle (content type)
│     │     └─ entity type
│     └─ config type (field instance)
└─ config object type

Common config types:

File prefix	What it configures
field.storage.node.field_xyz	Field storage (shared across bundles)
field.field.node.page.field_xyz	Field instance on a specific content type
core.entity_form_display.*	Form display / field widget settings
core.entity_view_display.*	View display / formatter settings
node.type.page	Content type definition
views.view.frontpage	A View
image.style.thumbnail	Image style

---

Core commands

Export — DB → YAML files

drush config:export
# or shorthand
drush cex

Writes all current DB config out to config/sync. Run this after making changes in the dashboard.

Import — YAML files → DB

drush config:import
# or shorthand
drush cim

Reads YAML files and applies them to the DB. Run this after deploying or pulling changes.

Preview what will change before importing

drush config:status
# or
drush cst

Shows a diff of what is different between the YAML files and the database. Always run this before cim in production.

Export a single config item

drush config:get field.field.node.pro_occupations.field_anz

Import a single config item

drush config:import --partial --source=/path/to/single/file/dir

---

Keeping DB and YAML files in sync

The golden rule

One source of truth per environment. Dev: edit in dashboard → export → commit. Staging/Prod: never edit in dashboard → always import from YAML.

Standard dev workflow

# 1. Make your changes in the Drupal admin dashboard (on dev)

# 2. Export config to YAML
drush cex

# 3. Review what changed
git diff config/sync/

# 4. Commit
git add config/sync/
git commit -m "Add field_anz to pro_occupations content type"

# 5. Push and deploy

# 6. On staging/prod — import
drush cim
drush cr

Checking sync status

drush cst

Output legend:

Symbol	Meaning
Only in DB	Config exists in DB but not exported to YAML — needs cex
Only in sync	Config in YAML but not in DB — needs cim
Different	Config exists in both but they don’t match

If the status is clean, DB and YAML are identical.

---

Dashboard edit vs editing YAML directly

	Drupal Dashboard	Edit YAML + drush cim
Changes go live	Immediately	After drush cim
Tracked in git	No	Yes
Deployable	No	Yes
Safe for production	Risky	Best practice
Good for complex changes	Yes	Tedious for complex config

When to edit YAML directly

• Bulk find/replace across many config files (e.g. rename a field)
• Resolving a git conflict in a config file
• Applying a change from another environment without dashboard access

---

Conflicts — when DB and YAML disagree

If someone edits the dashboard on staging without exporting, the DB and YAML will drift out of sync.

# See what's different
drush cst

# Force YAML to win (overwrites DB with YAML)
drush cim

# Force DB to win (overwrites YAML with DB)
drush cex

Pick one and commit. Never leave them out of sync.

---

After import — always clear cache

drush cr

Some config changes (especially field/display changes) won’t take effect until the cache is cleared.

---

DDEV workflow

ddev drush cex
ddev drush cim
ddev drush cst
ddev drush cr

See also: DDEV Cheatsheet