"Configuration.yaml": understand the configuration file of Home Assistant

5 minutes of reading
Guide purposes:
  • Understand the basic concepts related to the configuration file of Home Assistant
  • Difficulty level: bass
Concepts dealt with:
  • software configuration
Software components used:
GUIDE more indicated for:

All environments

Notes and disclaimer
  • qualsiasi modifica all'impianto elettrico dev'essere progettata ed effettuata da personale qualificato;
  • any changes implemented in probefore is a propersonal responsibility as well as a profirst risk and danger (the contents of the present page are purely educational);
  • any changes implemented in proprior to a device it voids the guarantee, quality approvals and certifications.
Driving review: 3.4


The popular personale HUB software Home Assistant provides various modes for its configuration and for integration of the most disparate home automation components and various types of services. Mainly, to act on its configuration (understood both as that relating to its components core both of the integrations of home automation components and services) acts on a file leader called "configuration.yaml“, A simple text file written in format YAML.

This file is usually placed in the directory responsible for configuring theHUB; for example, when Home Assistant is installed How applicense on the Raspbian operating system usually it is located at the path:


For installation HASSIOusually located at the route:

/ Config /

Or, always on HASSIO (but installed on Docker @ Raspbian):

/ Usr / share / hassium / homeassistant /

Basically it is of a text file containing a series of "blocks" (without a specific order), each of which rappresents a specific one Component / platform di Home Assistant, components that, when configured, define one or more additions (e.g. lights, switches, air conditioners and whoever has more than one) or the configuration specific features proprie dell 'HUB (eg the definition of the "geographical areas"). Apart from specific modifications (to automations, scripts, scenes), each modification foresees the rebootHUB in order to make them operational.

To give an example, when we wanted to integrate into home automation based on Home Assistant a light, say, of the series Magic, we would use the platform dedicated to it "Flux Led / Magic Light", Which is the" daughter "of the component"Light"

The "block" related to this integration would correspond to:

# Esempio di entry su configuration.yaml
  - platform: flux_led
    automatic_add: True

where the voice "light:"Defines the beginning of the component block"Light"And the sub-block"platform:”Defines the true entity e proere, prolearned by specifying the platform, or "flux_led"

  • un components (component) provides the core logic for specific features (eg "and "light", too");
  • a platform (platform) creates the connection to a specific software and / or hardware (for example "flux_led“).

Pay attention to the fact that indentation has a role determinant in defining the relationships defined in YAML - most of the configuration errors arise, in fact, from an incorrect indentation. Indented elements are nested within elements of a "higher" level. In the example above, “platform: flux_led" it's a proownership (nested) of the component "notify"
Each degree of indentation is defined by two spaces, not three, not one: the two.

By convention, indentation is defined through two spaces for each nesting level.
The lines preceded by the "#"Are ignored by the system.

Before giving any configuration to food a Home Assistant, it is always a good idea to validate the profirst YAML file through the site YAMLint.

Not all integrations require underlying platforms to be implemented, but they can be used and configured independently.

The example to follow shows a component configuration "Input Select" that progives a list of choice items (as a form of user input at the GUI level). As noted, no platform is indicated.

More proproperty (for example "name") Are specified using mappature. Notice how the second line is only "alzo_tapparelle:"Without any value on the same line. This is because in fact it opens up successive nesting lines to define its parameters:

    name: Alzo delle tapparelle
# Le opzioni di scelta vengono definite tramite la seguente mappatura
    - 0
    - 1
    - 2
    - 3
    initial: 0

The following example shows instead the nesting of a collection of mappature in a mappatura itself: in this case two are defined "Sensor"(Sensors) that use the platform"MQTT Sensor"Which have different" state topic "values ​​(one of the protypical properties of an MQTT sensor):

  - platform: mqtt
    state_topic: sensor/topic
  - platform: mqtt
    state_topic: sensor2/topic

In the configuration file configuration.yaml (as well as in the other sidecar files linked to it) you can use environment variables. To use one it is sufficient to indicate "! env_var”Followed by the name of the variable itself.
For example:

  api_password: !env_var PASSWORD

If the variable is not defined, it is possible to indicate in the configuration the value to be used alternatively:

  api_password: !env_var PASSWORD password_di_default  

Since the configuration expands also increases the length of the file, to improve its readability it is possible to indicate inside specific references to external files using the particle "!includes”Followed by the name of the file to include:

lights: !include lights.yaml

In essence it is possible to maintain "configuration.yaml"As" backbone "of the configuration and use multiple files (.yaml) as" ribs "in which to configure the entities deriving from the various components declared in the main file.

File subdivision "configuration.yaml"In several files sidecar is a technique that reduces complexity and increases manageability - therefore, on inDomus we have decided to dedicate to this theme an ad hoc page.

Configuration example

The following is, roughly (it may change from version to version), a "typical" configuration"Of Home Assistant:

  # Name of the location where Home Assistant is running
  name: Home
  # Location required to calculate the time the sun rises and sets
  latitude: 43.9092
  longitude: 12.9164
  # Impacts weather/sunrise data (altitude above sea level in meters)
  elevation: 0
  # metric for Metric, imperial for Imperial
  unit_system: metric
  # Pick yours from here: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones
  time_zone: Europe/Rome
  # Customization file
  customize: !include customize.yaml

# Show links to resources in log and frontend

# Enables the frontend

# Enables configuration UI

# Uncomment this if you are using SSL/TLS, running in Docker container, etc.
# http:
#   base_url: example.duckdns.org:8123

# Checks for available updates
# Note: This component will send some information about your system to
# the developers to assist with development of Home Assistant.
# For more information, please see:
# https://home-assistant.io/blog/2016/10/25/explaining-the-updater/

  # Optional, allows Home Assistant developers to focus on popular components.
  # include_used_components: true

# Discover some devices automatically

# Allows you to issue voice commands from the frontend in enabled browsers

# Enables support for tracking state changes over time

# View all events in a logbook

# Enables a map showing the location of tracked devices

# Track the sun

# Allow diagnosing system problems

# Sensors
  # Weather prediction
  - platform: yr

# Text to speech
  - platform: google

# Cloud

group: !include groups.yaml
automation: !include automations.yaml
script: !include scripts.yaml

As can be seen, a series of components are already listed and therefore active on the platform; others, of course, will be customized by hand.

In line, a good rappresentment of the concept of subdivision into multiple files of the configuration file.

How to modify the configuration file (s)

As explained in the opening, the modification of these text files is dependent on the type of system and installation of Home Assistant in use.
In the case of Raspbian + Home Assistant, it is possible to access the system via SSH (via terminal or via SFTP, via a typical FTP client) Filezilla) and overwrite / modify files; using HASSIOinstead, the most practical thing is that to install and use theadd-on "Configurator".

With systems like Windows e macOS the thing is trivial: just find the files on the hard disk and edit them directly with a text editor present on the operating system. We recommend the evergreen ATOM.

"Configuration.yaml": how to split the configuration file of Home Assistant

Home Assistant Official LogoATTENZIONE: remember that there is on our FORUM community an ad hoc section dedicated to Home Assistant, for any doubt, question, information on the specific merit of these components.


Stay up to date through ours Telegram channel!