Home Assistant Configuration YAML (The Beginners Guide)

Published Categorized as Home Assistant

Not so long ago I was new to Home Assistant and I clearly remember the initial learning curve when first delving into the configuration.yaml file.

Home Assistant is one of those platforms that seems mind boggling at first, yet once you grasp the basics it becomes pretty easy quite quickly. The first major milestone to overcome is understanding the primary configuration file, configuration.yaml.

What is YAML?

The fancy technical description of YAML is “human-readable data-serialization language.” It is basically a kind of programming language that is meant to be easy for a human reader to understand but also for a machine to interpret.

Originally YAML was said to mean Yet Another Markup Language, referencing its purpose as a markup language with the yet another construct, but it was then repurposed as YAML Ain’t Markup Language, a recursive acronym, to distinguish its purpose as data-oriented, rather than document markup


Don’t be put off by the description or think that it is impossible to understand for someone who does not have a background in computer programming.

To edit YAML in Home Assistant is as simple as writing a list, once you get to grips with the way the system refers to the various components.

There are other more graphical ways to configure Home Assistant such as Node Red. However I believe to truly get the most from Home Assistant it is best to learn the basics of YAML and write configuration in YAML files.

Home Assistant already provide an excellent guide on YAML, I would recommend reading it after this article for a deeper understanding.

What is configuration.yaml?

The configuration.yaml file is the main YAML file used by Home Assistant to gather all of the information about the users desired configuration.

It is like one big settings page, only the options are stored in a written list rather than by a bunch of switches and check boxes.

You can write your entire Home Assistant configuration in this one file if you prefer to keep things simple, no additional files needed!

My example tutorials on this site always assume that everything will be written in this one file. Although as your configuration grows in size you may want to split it up into several files.

When I write the tutorials here I make the assumption that a user who understands how to split up their YAML configuration will know enough to make the necessary amendments to the example code on my site.

However it is entirely optional so you can copy and paste everything from my tutorials directly into configuration.yaml and it should work just fine.

One very important point to mention about YAML is the tab/spacing is very important. You should maintain the correct tab/spacing to avoid any syntax errors.

Home Assistant file structure

Home Assistant creates a root directory structure, where the main configuration file configuration.yaml is located. All of the user defined configuration is read from this file.

The configuration.yaml file is located in the main configuration directory along with all other necessary configuration files. The location differs depending on the operating system used.

Home Assistant/config
OS X~/.homeassistant

If you want to change the default directory you can use the following command. However for simplicity it is probably best to leave it set to default.

hass --config path/to/config

How do you edit Home Assistant YAML files?

There are two ways that you can edit the YAML files in Home Assistant. The easiest way is to use the file editor add-on, however you can also edit them with your favorite text editor if you prefer.

File editor

In order to edit files with the built-in file editor, you first need to install it from the add-ons store. It can be found by clicking supervisor in the sidebar and then the add-on store tab.

One of the main advantages of using the file editor is the built-in tool to reference various elements you have in your Home Assistant setup. This saves a lot of time searching for the names of entities or the service that you require, for example.

There is also a handy settings menu where you can carry out various useful tasks. You can also create new tabs and restart Home Assistant from this menu, something that is required each time you wish changes in YAML files to take effect.

Another very useful feature of the file editor is it’s build-in syntax checking. YAML utilises spaces as part of it’s syntax and it is quite easy to produce a syntax error from incorrectly formatting the file.

A correctly formatted YAML file will be denoted by the green circle in the top right-hand corner.

Incorrect formatting such as incorrect indentation shown here by the red circle will be flagged by the editor. This is denoted by the red circle in the top right-hand corner.

Text editor

If you wish to use your favorite text editor then it is possible to access the files using Samba Share. This add-on can be installed from the add-ons store.

You can then access your files through the a file explorer interface in your OS. If you prefer to use a text editor then you should use one with syntax highlighting. My preference is Sublime Text available for Mac, Linux and Windows.

If you are working with a text editor external to the Home Assistant web user interface, you will not have the syntax checking ability of the built in file editor.

Instead you can connect to the supervisor using SSH and run the following command to check the integrity of the files.

ha core check

This will produce a confirmation if all files have the correct syntax.

However if there is something wrong the error will be given in the terminal. This is the error produced by an indentation formatting error.

How do you add integrations to configuration.yaml?

In Home Assistant an integration is a device that is supported by the platform. There are generic integrations for things such as lights and switches. There are also bespoke integrations for particular hardware offerings.

All integrations can be specified and configured within the configuration.yaml file. In order to do so we must add a component and platform.


At the top level we specify the component. There are many components supported but a good example of a common component would be automation or script.

Let’s look at an example for the light integration. In order to add the light component, we simply add this to our YAML file.



It should be noted that a component is usually only added once. For example the component light would be written once in the YAML file and all platform instances would be listed beneath with indentation.

For this example we can add a group platform to the light component. This specifies the platform as group, gives it a name and specifies the lights that we wish to include in the group. We call the devices within Home Assistant entities, therefore we will specify two light entities.

   - platform: group
     name: Studio Lights 1
      - light.bulb_1
      - light.bulb_2

Now if we wish to create another group, we will add another platform instance beneath this code, but we do not add the light component again.

   - platform: group
     name: Studio Lights Group 1
      - light.bulb_1
      - light.bulb_2
   - platform: group
     name: Studio Lights Group 2
      - light.bulb_3
      - light.bulb_4

It takes a little time to get used to the syntax within Home Assistant YAML and to gain an understanding of what to write. Stick with it! You will be surprised at how quickly you pick it up

Beginner YAML tips

  • Make sure you maintain the correct spacing. Indentation is very important and it is the primary reason for errors.
  • If you have an error and you are unsure what is causing it, it is almost always due to indentation so check the formatting!
  • I would recommend using the built-in file editor. Make use of the search entities and services feature as a reference to the objects you wish to include.
  • Start by keeping everything in one single YAML file, your configuration.yaml file. It makes sense to split up the files later but wait until you are comfortable with basics first.
  • Don’t over-complicate your setup when you are starting out. Start by getting a good understanding of how to use a simple light entity and including it in automations.
  • Copy and paste some examples into your own configuration and start by adjusting the attributes such as changing the entities to your own devices. It’s a great way to get familiar with YAML before you try writing something from scratch.
  • Check out the Cookbook on the Home Assistant website for some great examples!


YAML is a powerful part of Home Assistant and it is what gives it the flexibility that you don’t get with closed source and/or commercially available solutions to home automation.

In this modern era many people have an Alexa or Google device running their home automation. However these commercially available devices over-simplfy everything and just don’t offer anywhere near the number of possibilities offered by a Home Assistant setup.

Learn YAML and harness the full power of Home Assistant to really blow your neighbours socks off!

Now you have a basic understanding of the concepts of YAML, why not dive right in and give my automation or script tutorial a try!