What Home Assistant’s configuration.yaml file does (and why you should care)
Although it’s almost infinitely customizable, Home Assistant may seem relatively simple on the surface. Sometimes, however, you may find that you need to set up integrations or make changes manually, and at that point you might be directed to the configuration.yaml deposit.
Here’s what this file does, how to modify it, and why you probably don’t need to worry too much about it.
THE configuration.yaml the file serves multiple purposes
THE configuration.yaml The file is a set of instructions usually located under the config directory on your Home Assistant server. The YAML extension refers to the type of formatting used in the file (initially thought to be short for Yet Another Markup Language, eventually adapted to YAML Ain’t Markup Language).
The YAML format is designed to be human-readable code, using simple rules like indentation. It is widely used on the Home Assistant platform, for example in automations and scripts. It’s designed with the goal of being accessible, so formatting isn’t a barrier to entry, although you’ll naturally still need to understand basic Home Assistant concepts like entities and values.
Arguably the main reasons you may want to make changes to the configuration.yaml need to use certain automations or make changes to how Home Assistant works outside of the main user interface.
The vast majority of integrations you’ll encounter when using the platform are added through the main user interface, with convenient control panels and setup processes. If you decide to think a little more outside the box and install integrations outside of the main version of Home Assistant, for example from the Home Assistant Community Store, you may find that you need to make changes to the configuration.yaml so that these integrations run when your server starts.
This may be as simple as adding a few lines of code that you can copy and paste, or it may require a more complex configuration process where you set parameters so that the integration does what you want. I once added a transit-focused integration to my Home Assistant dashboard that required me to connect to the necessary API and reference the correct stop and trip data in the YAML.
Another use of configuration.yaml The file is when modifying the operation of Home Assistant. A good example is customizing the sidebar to create shortcuts to different parts of the platform.
The file is also used to call other YAML files containing scripts, automations, scenes and your frontend themes. While there’s no reason to edit most of them, you can add your own if you want.
Changing the configuration.yaml deposit
You can change the configuration.yaml file using a regular text editor, provided you have access to it. Most will find it under /config/ directory on your server, while Docker users will find it under kernel /homeassistant/ directory.
If you are running Home Assistant on a server like a Raspberry Pi or using a virtual machine to run Home Assistant on another operating system; Accessing this file can be a pain. Fortunately, there is an easy way to get around this problem using an add-on called File Editor.
You can install the File Editor add-on under Settings > Add-ons by clicking the “Add-ons Store” button and searching for it. Once configured, launch the File Editor under Settings > Add-ons > File Editor > Open Web UI. I created a shortcut for this to make things even easier.
By default, your configuration.yaml the file will be the first to open. Here you can add any rows you want and use comments (#) above each to add descriptions so you know what the different sections do. When you’re done, click the red “Save” pen button at the bottom of the screen.
In order to follow up on any changes made to your configuration.yaml file, you will need to restart Home Assistant. You can do this through the Settings menu by clicking the “three dots” in the upper right corner of the page and choosing “Restart Home Assistant.”
Another option is to exhibit your /homeassistant/ directory via a network share by installing the Samba sharing add-on and connecting to your server through another computer on the network. From there you can open the configuration.yaml file in a text editor and make any changes you want.
Don’t worry until you need it
As indicated, the configuration.yaml The file is not something you will need to interact with until you suddenly find that you need to. The integrations you’ll use every day are built around simple user interfaces and don’t need to be called manually using this file.
Sometimes you might find an obscure integration that you need to use to integrate a niche device or service into your server. Having to play with the configuration.yaml doesn’t mean the integration isn’t worth your time, and you shouldn’t be afraid to use it.
As always, just make sure you have a Home Assistant backup set up so you can undo any unwanted changes and restore your server if necessary.
