Inclusiones YAML en Home Assistant: !include y directorios

Revisión técnica: 27 de octubre de 2026. Esta es una guía complementaria procedente del curso anterior, no un capítulo numerado del nuevo. Para seguir el itinerario, consulta el curso actual de YAML en Home Assistant.

Home Assistant permite dividir su configuración mediante !include y variantes para directorios. Corrección importante: los nombres !include_list y !include_dict que aparecían en esta URL no son directivas incorporadas de Home Assistant. Se han retirado los ejemplos que los recomendaban. La URL se mantiene mientras termina la transición del curso.

Importar un archivo: !include

La elección no depende de llamar al archivo «lista» o «diccionario», sino de que su contenido tenga la estructura que espera la clave donde lo insertas. En el archivo principal puedes tener:

automation: !include automations.yaml
script: !include scripts.yaml
scene: !include scenes.yaml

No añadas estas claves por segunda vez si ya existen. Conserva el resto de tu configuración. En automations.yaml debe haber una lista de automatizaciones, sin repetir automation:. En scripts.yaml debe haber un mapa de identificadores de scripts, sin repetir script:.

Ejemplo completo de estructuras diferentes

Contenido de automations.yaml, sustituyendo la entidad de la luz por una real:

- id: ejemplo_aviso_atardecer
  alias: "Ejemplo: luz al atardecer"
  triggers:
    - trigger: sun
      event: sunset
  actions:
    - action: light.turn_on
      target:
        entity_id: light.entrada
  mode: single

Contenido de scripts.yaml. Aquí no hay guion inicial: el nivel superior es un mapa de nombres:

encender_entrada:
  alias: "Encender entrada"
  sequence:
    - action: light.turn_on
      target:
        entity_id: light.entrada

Incluir carpetas: qué devuelve cada variante

Directiva	Contenido y resultado
!include archivo.yaml	Carga un archivo. Conserva su estructura: lista, mapa o valor; no convierte una lista en mapa.
!include_dir_list carpeta/	Crea una lista cuyos elementos son los contenidos de los archivos. Si cada archivo contiene una lista, el resultado puede ser una lista de listas.
!include_dir_named carpeta/	Crea un mapa: cada nombre de archivo, sin extensión, es una clave.
!include_dir_merge_list carpeta/	Combina las listas de los archivos en una sola lista.
!include_dir_merge_named carpeta/	Combina los mapas de los archivos en un único mapa. Evita claves duplicadas.

Por ejemplo, si cada archivo de automatizaciones/ contiene una lista de automatizaciones como la anterior, puedes reunirlas así:

automation: !include_dir_merge_list automatizaciones/

Esto sustituye la entrada anterior de automation:; no es una segunda clave para pegar debajo. No cambies la estructura de archivos que gestione la interfaz sin comprobar sus requisitos. Un validador YAML genérico puede rechazar estas etiquetas porque las interpreta el cargador específico de Home Assistant.

Antes de reiniciar

Haz una copia de seguridad, comprueba las rutas relativas y valida la configuración con Home Assistant. Un archivo puede ser YAML válido y seguir siendo incompatible con la integración que lo recibe. Tampoco debes suponer que las anclas de un archivo estarán disponibles en otro cargado por separado.

Referencia: documentación oficial de inclusiones de Home Assistant.