Home Assistant uses the YAML syntax for configuration. YAML might take a while to get used to but is powerful in allowing you to express complex configurations.
While more and more integrations are configured through the UI, for some, you will add code in your
configuration.yaml file to specify its settings.
- An integration provides the core logic for some functionality (like
notifyprovides sending notifications).
- A platform makes the connection to a specific software or hardware platform (like
pushbulletworks with the service from pushbullet.com).
The basics of YAML syntax are block collections and mappings containing key-value pairs. Each item in a collection starts with a
- while mappings have the format
key: value. This is somewhat similar to a Hash table or more specifically a dictionary in Python. These can be nested as well. Beware that if you specify duplicate keys, the last value for a key is used.
In YAML, indentation is important for specifying relationships. Indented lines are nested inside lines that are one level higher. In the above example,
platform: pushbullet is a property of (nested inside) the
Getting the right indentation can be tricky if you’re not using an editor with a fixed-width font. Tabs are not allowed to be used for indentation. The convention is to use 2 spaces for each level of indentation.
To check if your YAML syntax is correct before loading it into Home Assistant, you can use the third-party service YAML Validator (not maintained by the Home Assistant community).
Pay attention to not storing private data (passwords, API keys, etc.) directly in your
configuration.yaml file. Private data can be stored in either a separate file or in environmental variables, which circumvents this security problem.
Strings of text following a
# are comments and are ignored by the system.
The next example shows an input_select integration that uses a block collection for the values of options.
The other properties (like
name:) are specified using mappings. Note that the second line just has
threat: with no value on the same line. Here threat is the name of the input_select and the values for it are everything nested below it.
name: "Threat level"
# A collection is used for options
The following example shows nesting a collection of mappings in a mapping. In Home Assistant, this would create two sensors that each use the MQTT platform but have different values for their
state_topic (one of the properties used for MQTT sensors).
- platform: mqtt
- platform: mqtt
On Home Assistant Core installations, you can include values from your system’s environment variables with
Note that this will only work for Home Assistant Core installations, in a scenario where it is possible to specify these.
Regular Home Assistant users are recommended to use
!include statements instead.
password: !env_var PASSWORD
If an environment variable is not set, you can fall back to a default value.
password: !env_var PASSWORD default_password
To improve readability, you can source out certain domains from your main configuration file with the
light: !include lights.yaml
More information about this feature can also be found at splitting configuration.
If you see the following message:
found character '\t' that cannot start any token
This means that you’ve mistakenly entered a tab character, instead of spaces.
Home Assistant is case sensitive, a state of
'on' is not the same as
'ON'. Similarly an entity of
group.Doors is not the same as
If you’re having trouble, check the case that Home Assistant is reporting in the dev-state menu, under Developer tools.
ON all as
false. This means that if you want to set the state of an entity to
on you must quote it as
'on' otherwise it will be translated as setting the state to true. The same applies to
Not quoting the value may generate an error such as:
not a valid value for dictionary value @ data