Variables de entorno YAML

Este artículo puede contener enlaces de afiliado. Si compras desde estos enlaces, el precio para ti es el mismo y la tienda me paga una pequeña comisión que ayuda a mantener Tecnoyfoto.

Albert BarnosellEditor y responsable de Tecnoyfoto

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.

Las variables de entorno son valores del proceso del sistema operativo. YAML no las lee automáticamente: en Home Assistant se consultan mediante su etiqueta específica !env_var. Es una técnica útil si controlas cómo se inicia Home Assistant, pero no equivale a poner una variable en cualquier terminal de otro ordenador.

Ventajas y límites reales

Separar un valor del archivo principal facilita cambiarlo entre entornos y reduce el riesgo de compartirlo por accidente. Sin embargo, una variable de entorno no es un almacén cifrado: puede quedar expuesta en la configuración del contenedor, herramientas de diagnóstico o procesos con permisos suficientes. No publiques archivos ni capturas con credenciales reales.

El proceso correcto debe recibir la variable

En un terminal Linux o macOS, export afecta a esa sesión y a sus procesos hijos:

export HA_NOMBRE_INSTALACION="Casa de pruebas"

Editar .bashrc no garantiza que un servicio, un contenedor o Home Assistant OS lean esa variable. En una instalación Container, debe declararse en el entorno del propio contenedor; en un servicio, en su mecanismo de arranque. Tras cambiar el entorno normalmente hay que recrear o reiniciar el proceso correspondiente. No modifiques archivos gestionados de Home Assistant OS como si fueran los de una instalación manual.

PowerShell: sintaxis correcta y alcance

Para la sesión actual y los procesos que arranque desde ella:

$env:HA_NOMBRE_INSTALACION = "Casa de pruebas"

Para guardar una variable de usuario en Windows:

[Environment]::SetEnvironmentVariable("HA_NOMBRE_INSTALACION", "Casa de pruebas", "User")

El segundo ejemplo no actualiza mágicamente procesos ya abiertos ni el entorno de un contenedor de Linux. No existe un cmdlet estándar de PowerShell llamado Set-EnvironmentVariable; no lo confundas con el método de .NET. Son ejemplos explicativos: no se han ejecutado en el ordenador del lector.

Leer el valor en Home Assistant con !env_var

Si el entorno del proceso de Home Assistant contiene la variable anterior, una entrada válida en configuration.yaml es:

homeassistant:
  name: !env_var HA_NOMBRE_INSTALACION

Si ya existe homeassistant:, añade o cambia name: dentro de ese bloque, sin duplicar la clave. También puedes definir un valor de reserva con la sintaxis documentada:

homeassistant:
  name: !env_var HA_NOMBRE_INSTALACION Casa

Estas son alternativas, no dos bloques para pegar juntos. La etiqueta documentada es !env_var, no !env_var_list. Lee una variable, no convierte automáticamente una serie de variables en una lista ni configura una integración por su nombre.

Base de datos y MQTT: por qué se retiraron los ejemplos antiguos

Una clave arbitraria database: con host, puerto y contraseña no configura Recorder de Home Assistant. Debes usar el esquema de la integración correspondiente, sus requisitos de conexión y un controlador compatible. Del mismo modo, no copies antiguos bloques de conexión MQTT con broker, username y password esperando configurar la integración actual: la conexión MQTT se gestiona desde su configuración en la interfaz.

Que una integración se configure desde la interfaz no significa que sus formularios evalúen !env_var. Esta etiqueta pertenece al cargador YAML y solo tiene sentido dentro de una configuración YAML admitida. Por eso se han retirado ambos ejemplos, en lugar de cambiar únicamente el nombre de la etiqueta y dejar un esquema incorrecto.

Variables de entorno frente a secrets.yaml

En configuraciones YAML compatibles, !secret lee un valor de secrets.yaml; !env_var lo obtiene del entorno del proceso. Elige según tu instalación y procedimiento de despliegue. Ninguno de los dos mecanismos cifra por sí mismo la información. Protege permisos, copias de seguridad y repositorios. Si compartes un archivo, revisa también URLs, comentarios y nombres que puedan revelar información privada.

Comprobaciones antes de aplicar cambios

Haz una copia, confirma qué instalación utilizas y cómo recibe el entorno. Valida la configuración con Home Assistant antes de reiniciar y consulta los registros si falta una variable. No vuelques todo el entorno ni las contraseñas a registros para depurar. Un validador externo puede no entender las etiquetas personalizadas; utiliza ejemplos ficticios si necesitas compartir un fragmento.

Fuentes: variables de entorno en Home Assistant y alcance de las variables en PowerShell.

Continúa leyendo

Siguiente guía relacionada · 3 min de lectura

Variables en YAML: Guía 2026 para reutilizar código

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…

Continuar con este artículo↓