Splitting Up Configuration.yaml in Home Assistant

In this guide, I’m going to show you how to split up your configuration.yaml file. This will allow you cleanup and organize all of the packages, binary sensors, automations, or template sensors into their own configuration files.

Rather than keeping everything in one large file, you will add an !include reference in your configuration file that points to their respective file.

---

Why Split Up Your Configuration file?

There are a number of reasons you might want to split up your configuration.yaml file. The biggest advantage is that it allows you to cleanup (or refactor) everything and categorize everything into their own file or folder.

For example, my config is currently 603 lines long. 99% of the time, I rarely need to to see or edit most of the stuff in there. Rather than scrolling past it until I find the correct section, I’m going just include a reference in the config file and completely remove it from the config file. Doing this also makes editing parts of your config much easier later on. For example, if I know I need to edit my utility meter sensors, I can just open my utility_meter.yaml file.

This same process applies when using secrets to securely store your credentials in your secrets.yaml file.

If interested, you can follow this guide to store secrets in Home Assistant. after you learn to split up your YAML.

---

Before We Start

Before you get started, take a backup! I recommend using the Home Assistant Google Drive Backup or Samba Backup addon. There’s a good chance you will incorrectly format something during this process, so making a backup before refactoring is an absolutely must.

It’s also important to point out that there are many different ways to split up your yaml. I’m going with a very flat method, where all new files are created in the same root directory (/config). Since I’m using VSCode, I’m going to add shortcuts to the VS Code sidebar for quick access later on.

configuration.yaml

–groups.yaml

–switch.yaml

–input_number.yaml

–sensor.yaml

….etc.

However, there are other ways to do this. For example, you can split things up into separate folders if you’d like. You could add all entities to a folder and reference that instead of putting ALL sensors in the same file. I’m not going to show you how to do that in this guide, but I figured it’s important to point out.

---

Moving Your First Block

First, navigate to your configuration.yaml file. Locate something that you’d like to move. For this first example, I’m going to move my input_number block to it’s own file.

---

Add !include to config file

Before you move it, add this line to your configuration.yaml file.

input_number: !include input_number.yaml

---

Create new file

The name of this block is input_number, so we need to create a new file called input_number.yaml. Click the folder at the top > New File.

Name the file input_number.yaml:

Then, find the input_number block in your configuration.yaml file and copy to clipboard. You don’t need to copy the name input_number; you can just copy everything below it:

Then, paste it into the newly created input_number.yaml file. It will probably be formatted incorrectly, so just backspace twice. (or use CTRL+A to highlight all > Shift+Tab to move the yaml to the left)

It will now look like this:

Save the new file

Then, just save the new file.

The last step is to delete the original block of code from your configuration file, since you are now referencing it from the input_number.yaml file instead of configuration.yaml directly.

Finally, restart Home Assistant from Configuration > Check Configuration > Reboot.

---

Move More Blocks

After you confirmed everything is working, the process is basically rinse and repeat for the remaining blocks. Next, I’m going to move my binary sensors to their own file.

1. Add !include binary_sensor.yaml to configuration.yaml.
2. Create new binary_sensor.yaml file.
3. Copy binary sensor code from configuration.yaml file and paste into binary_sensor.yaml file.
4. Delete old code from configuration.yaml file
5. Save and reboot.

---

Accessing new !include Files

Now that you’ve split up your configuration, anytime you need to add a new sensor, you can either open File Editor and scroll down to the find the appropriate file:

Or, if using the VS Code addon, you can access it a little easier right from the sidebar:

---

Wrapping Up

Splitting up your configuration files makes sense the longer you start to tinker with Home Assistant. This is entirely optional, but it does help you quickly find your automations, sensors, templates, and so on much easier so you don’t have to scroll through one huge file each time you need to make a small change.

In a future guide, I’ll show you how to use secrets to securely store your usernames, passwords, email addresses, and API keys so they are sitting in plain text in your main config file, but the process is basically the same. You reference !secrets in the config file anytime you need to add a password, and then add the password field to your secrets.yaml file.