I’m just going to come out and say it. My Home Assistant configuration files were a mess before I took some time to organize them. The configuration.yaml file was filled with code and disorganized. My automations were all in one file, and I have over 100 automations. My scripts were in a similar situation. Over time, I built up dozens of sensor and binary_sensor templates, all in my configuration.yaml file. After appearing on the Home Assistant podcast and receiving encouragement (chastisement?) to split my files up by hosts Phil Hawthorne and Rohan Karamandi, I decided to get organized.
Table of Contents
Background
I want to make sure you know this article isn’t a discussion of the best ways to organize your Home Assistant configuration files. This article will point out a few options for you to consider. However, it will focus on what I decided to do and how I decided to do it. I hope this provides a practical example that helps some of you.
The starting state of my Home Assistant configuration files
I’ve been using Home Assistant for three years. In that time I’ve greatly expanded Home Assistant’s reach into my smarthome by writing numerous automations and adding integrations. What I haven’t done is spend much time planning or pruning my Home Assistant configuration files.
I had all of my automations sitting in one file large file (automations.yaml). I had all of my scripts in one file too (scripts.yaml). My configuration.yaml was filled with countless sensors, binary sensors, lights, switches, you name it. It actually had more lines than my automations.yaml file. It was getting hard to find things and manage the files.
Mainly, I wanted to make each of the configuration options more manageable. I didn’t want to scroll and search through long files just to find the small places I wanted to make changes. I wanted it to be easier to track down bugs (usually typos) in my configurations. Sustainability for growth in my configurations is also a key consideration. It should be obvious where to put new code.
Home Assistant configuration file organization options
Home Assistant has a few options for splitting up code. Their documentation explains these options in detail. I’ll summarize:
- You can use includes to simply move an entire integration into a new individual file or files.
- You can use more advanced versions of the includes to move entire integrations into files of a directory. Examples will help explain these options.
Basic include options
Let’s start with the simplest example:
automation: !include automations.yaml
This line, when placed in your configuration.yaml file, tells Home Assistant that your automation code is in a file called automations.yaml in your config directory. Similarly, you can break out more parts of your configuration.yaml file:
automation: !include automations.yaml switch: !include switches.yaml light: !include lights.yaml
The above example moves automation, switch, and light code to separate files.
Advanced include options
For the advanced options, I’ll copy the explanations directly from the Home Assistant documentation:
!include_dir_listwill return the content of a directory as a list with each file content being an entry in the list. The list entries are ordered based on the alphanumeric ordering of the names of the files.!include_dir_namedwill return the content of a directory as a dictionary which maps filename => content of file.!include_dir_merge_listwill return the content of a directory as a list by merging all files (which should contain a list) into 1 big list.!include_dir_merge_namedreturns the content of a directory as a dictionary by loading each file and merging it into 1 big dictionary.
Let’s walk through an example of each of these:
automation: !include_dir_list automations/
In this case, each individual automation would be contained in its own YAML file inside the directory automations/. So you can have files turn_on_lights.yaml and turn_off_lights.yaml in the automations directory that each has on automation inside them.
Contrast this with:
automation: !include_dir_merge_list automations/
In this case, each YAML file in the directory automations/ can have multiple automations inside. You could put the automations to turn the lights on and off in a file called lights.yaml. The key thing to remember when using a merge_list directive is that all the automations in all the files have to be in a list format (with a hyphen), e.g.:
- alias: "Turn on Light"
trigger:
- platform: state
entity_id: device.iphone
to: "home"
action:
- service: light.turn_on
target:
entity_id: light.living_roomnot:
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 merge them into a dictionary. For example, scripts are loaded into a dictionary, so you’d want to use these instead of the list includes, e.g.
script: !include_dir_named scripts/
to merge files in the scripts directory that each contains one script, or
script: !include_dir_merge_named scripts/
to merge files in the scripts directory that can contain more than one script.
What I decided to do
I decided to use a combination of the include directives to split up my configuration file. I organized my automations as a merged list. This way I can keep groups of automations in one file. For example, I have a file called irrigation.yaml for my irrigation automations, and a file called hvac.yaml for my heating and cooling system automations. Similarly, for my scripts, I created a merged dictionary.
For sensors, binary sensors, lights, switches, groups, remote, shell commands, REST commands, and input_numbers I used a simple include directive to store all of them in their own file. I don’t tweak or add to these as much as I do scripts, and there aren’t as many of them, so I think a separate file for each is okay. 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
Notice lines 2 and 3 above. I have a regular include directive and a merge list directive for automations. This allows me to organize the automations I write in files, while automations generated by the UI will still be stored in automations.yaml.
What about packages?
Another way I could have organized my files is by using packages. Packages allow you to bundle integrations (e.g. light, switch, input_boolean, etc.) together. You can combine packages with include directives for more logical groupings of features in your configuration. For instance, you could have a home theater package that contains all the lights, A/V equipment, and automations for that room in one package. I need to look into this further, and I may consider organizing my configuration in packages in the future.
Final thoughts
I hope you leave this article with some idea about how to organize your Home Assistant configuration files. I’d love to hear how you do it (I’m no expert). Let me know in the comments or on Twitter!
