Including default config in config/installfor Drupal 8 , 9 , 10 , and 11

Home » Module Development » Including default config in config/install
Last updated :  
8.x , 9.x , 10.x , 11.x

The last lesson ended on an awkward truth: a freshly installed weather module has no API key and no default location, because nothing has ever called set() on its config. Every visitor sees "not configured yet" until someone manually opens the settings form. Real modules don't ship broken by default — they ship with sensible starting values already in place. That's what config/install/ is for.

What you'll learn in this lesson

  • Where default configuration actually lives, and when Drupal reads it
  • How to write a default config YAML file that matches your schema
  • Why the file name has to match the config object's name exactly
  • What happens to this file after the module is installed

Shipping default settings for the weather module

Default configuration lives at config/install/{config_name}.yml — for the weather module, that's config/install/weather_module.settings.yml:

api_key: ''
default_location: 'London'

The moment this module is installed (drush en weather_module, or via the UI), Drupal reads every file in config/install/ and imports it directly into the active configuration — no PHP code, no install hook, required. The file's name, minus the .yml extension, must match the config object's name exactly (the same name you used in the schema file two lessons ago), or Drupal won't associate the two at all.

This file is a one-time seed, not a live source of truth

This is the detail that trips people up: config/install/weather_module.settings.yml only matters at the moment of installation. The instant it's imported, the database becomes the real, live copy — editing this file after the module is already installed on a site does nothing, since Drupal never re-reads it. If a site builder changes the default location to "Paris" through the settings form, that change lives in the database; the file on disk still says "London" forever, and that's fine — it's a template for new installs, not a synced mirror.

Real Examples module reference: config_entity_example ships config/install/config_entity_example.robot.marvin.yml — a real default config entity ("Marvin, the paranoid android") that appears the instant the module is enabled, exactly the same mechanism as the weather module's settings file above.

Quick check: you update config/install/weather_module.settings.yml to change the default location from "London" to "Paris," then run drush updb on a site where the module is already installed. Does the live site's default location change to Paris? (Answer: no — config/install is only read once, at install time. Changing already-active configuration on existing sites requires an actual update hook, which is exactly what the next lesson covers.)

Key takeaways

  • Default configuration lives at config/install/{config_name}.yml and is imported automatically the moment the module is installed — no code required.
  • The file's name (minus .yml) must exactly match the config object name used in its schema file.
  • This file is a one-time seed for new installs; it is never re-read on an already-installed site, even if you edit it and update the module.
  • The database, not the file, is always the live source of truth once the module is installed.

Coming up next

So how do you change a default on a site where the module is already installed? The final lesson in this section covers hook_update_N() — the mechanism for making configuration changes ship correctly to sites that installed the weather module long before your update existed.