Once upon a time, there was complete chaos in my Home Assistant configuration files, and it took a while before I put them in order. The configuration.yaml file was oversaturated with code and disorganized. My automations were in one file, and I have over 100 automations. All of my scripts were in a similar situation. Over time, I’ve created dozens of templates for sensors and binary_sensor, all in their “configuration.yaml” files. After getting confused about the configuration and settings, I decided on “general cleaning.”

Preamble

I should note that this article isn’t a discussion of the best ways to organize Home Assistant configuration files. Here are some points to keep in mind. I will focus on the configuration process for Home Assistant and what and how I decided on specific settings. I hope my experience can help you.

The initial state of Home Assistant configuration files

I have been using Home Assistant for almost three years. During this time, I’ve developed and expanded the capabilities of Home Assistant, making it a powerful tool for managing my smart home. Though, I didn’t plan or shorten my configuration files.

All my automations were in one big file (automations.yaml). Also, all my scripts were in one file (scripts.yaml). My configuration.yaml included a lot of sensors, lamps, switches, and more. It became difficult to find and manage files.

I wanted to make each of the configuration items more manageable. I didn’t want to have to scroll and search through long files to make minor edits. I want to make it easier to track errors in my configurations. I need to understand where to add new code.

Settings of the Home Assistant configuration file

Home Assistant has several code-splitting options. Their documentation explains these options in detail.

You can use “include” to move all of the integration to a new separate file(s).
You can use more advanced “include” versions to move full integrations to folders with files.
Examples will help in explaining those options.

The basics of the include setting

Let’s begin with the most simple example:

automation: !include automations.yaml

This line placed in your configuration.yaml file tells Home Assistant that your code is in the file called automations.yaml in the same configuration folder. Similarly, you can split more parts of your configuration.yaml file:

automation: !include automations.yaml
switch: !include switches.yaml
light: !include lights.yaml

The example above moves the code for automation, switches, and lighting devices to separate files.

Advanced include options

For advanced options, I will copy the explanation from the Home Assistant documentation:

• !include_dir_list will return the contents of a directory as a list. The contents of each file will be an entry in the list. The list entries are ordered based on the alphanumeric order of the file names.
• !include_dir_named will return the contents of a directory as a dictionary that displays filename => file contents.
• !include_dir_merge_list will return the contents of a directory as a list by merging all the files into one list.
• !include_dir_merge_named returns the contents of a directory as a dictionary, loading each file and merging them into one dictionary.
  Let’s look at an example of each of them:

automation: !include_dir_list automations/

In this case, each automation would be in its YAML file inside the automations/ directory. So you can have turn_on_lights.yaml and turn_off_lights.yaml files in the automations directory, each with its automation.

Compare this with:

automation: !include_dir_merge_list automations/

In this case, each YAML file in the automations/ directory can have multiple automations inside. You can write rules for turning lights on and off in a file called lights.yaml. The thing to remember when using the merge_list directive is that all automations in all files must be in list format (hyphenated), for example:

- alias: "Turn on Light"
  trigger:
    - platform: state
      entity_id: device.iphone
      to: "home"
  action:
    - service: light.turn_on
      target:
        entity_id: light.living_room

but not:

alias: "Turn on Light"
trigger:
  - platform: state
    entity_id: device.iphone
    to: "home"
action:
  - service: light.turn_on
    target:
      entity_id: light.living_room

!include_dir_named and !include_dir_merged_named work similarly, but instead of merging files into a list, they combine into a dictionary. For example, scripts load into a dictionary. Use an entry instead of a list like this:

script: !include_dir_named scripts/

to combine files in the scripts directory, each containing one script, or

script: !include_dir_merge_named scripts/

to combine files in the scripts directory, which could contain more than one script.

What I decided to change

I used a combination of include directives to split up my configuration file and organized my automations as a merged list. This way, you can store automation groups in one file. For example, I have irrigation.yaml file for irrigation automation and an hvac.yaml file for heating and cooling automation. I also created a unified dictionary for my scripts.

For sensors, lamps, switches, groups, shell commands, and input_numbers, I used a simple include directive to keep them in their files. I don’t tweak and add and change them as often as automations, and there aren’t that many, so I think a separate file for each is fine. Here is the relevant section of my configuration.yaml:

group: !include groups.yaml
automation: !include automations.yaml
automation mine: !include_dir_merge_list automations/
script: !include_dir_merge_named scripts/
sensor: !include sensors.yaml
binary_sensor: !include binary_sensors.yaml
switch: !include switches.yaml
light: !include lights.yaml
rest_command: !include rest.yaml
remote: !include remote.yaml
shell_command: !include shell.yaml
input_number: !include input_number.yaml

Note lines 2 and 3 above. I have a regular include directive and a merge list directive for automations, which allows me to organize the automations I write into files while the automations generated by the UI will still be in automations.yaml.

But what about packages?

Another way to organize your files is to use packages. Packages allow you to bundle integrations (like light, switch, input_boolean, etc.) together. You can combine packages with include directives to group functions in your configuration more logically. For example, you can have a home theater package that will include all the lighting, audio-video equipment, and automation for the room in one package.

Last thoughts

I hope that after this article, you will have new ways to organize your Home Assistant’s configuration files. I’d love to hear how you do it. Let me know in the comments.