Skip to content
Home Assistant

YAML ‘Variables’ Are a Myth. Here’s How You *Actually* Reuse Code in 2026.

07/02/2026

Last updated on February 7, 2026

Mastering YAML variables is a game-changer for anyone working with config files, especially in the world of IoT and smart homes. In 2026, where automation is king, understanding how to use variables will let you write cleaner, more maintainable, and scalable code. This guide will take you from the basic concepts to advanced applications, becoming your go-to reference.

Variables help us avoid repetition (the DRY principle: “Don’t Repeat Yourself”) and manage sensitive data securely—something absolutely critical in systems like Home Assistant. If you’re just starting out, I highly recommend checking out our complete YAML course to build a solid foundation.

What Are YAML ‘Variables’, Really?

Here’s the deal: pure YAML doesn’t actually have “variables” in the way a traditional programming language does. Instead, it uses a clever system of Anchors (&) and Aliases (*) to reuse snippets of code. However, in practice, most platforms that rely heavily on YAML (like Home Assistant, Ansible, or Docker) extend its functionality to allow for a more intuitive variable-like system.

In this article, we’ll cover both: YAML’s native anchors and the platform-specific variables you’ll use in your day-to-day projects.

The Native YAML Way: Anchors and Aliases

The built-in method for creating a reusable value in YAML is with anchors. You define a value once with an anchor (&anchor_name) and then reference it anywhere else in the same document with an alias (*anchor_name).

This is incredibly useful for centralizing values that appear multiple times, like IP addresses, usernames, or device configurations. Remember, YAML syntax is strict about indentation, so pay close attention.

Practical Example: Imagine you have several sensors in the same room. Instead of typing “Living Room” over and over, you can use an anchor.

# We define an anchor for the location
default_location: &location Living Room

temperature_sensor:
  name: "Living Room Temperature"
  location: *location
  
humidity_sensor:
  name: "Living Room Humidity"
  location: *location

motion_sensor:
  name: "Living Room Motion"
  location: *location

If you ever decide to rename “Living Room” to “Family Room,” you only have to change it in one place. To dive deeper into this technique, check out our guide on YAML anchors and aliases.

YAML Variables in Smart Homes: Home Assistant 2026

Where the concept of variables truly shines is on platforms like Home Assistant. Here, it’s expanded to interact with the system, templates, and external files, making your YAML configuration far more powerful.

Handling Secrets and Sensitive Data

Never, ever, write passwords, tokens, or API keys directly in your main configuration files. For this, Home Assistant uses a special file called secrets.yaml.

From your configuration.yaml, you can then call these variables using the !secret directive.

Example in secrets.yaml:

# This file holds sensitive information
api_key_openweathermap: YOUR_API_KEY_HERE
user_mqtt: my_mqtt_user
password_mqtt: my_secure_password

Example of use in configuration.yaml:

weather:
  - platform: openweathermap
    api_key: !secret api_key_openweathermap

mqtt:
  broker: core-mosquitto
  username: !secret user_mqtt
  password: !secret password_mqtt

This method is essential for sharing your configuration online without exposing critical data. Learn how to set it up step-by-step in our guide to the secrets.yaml file.

Using Template Variables for Dynamic Automations

YAML templates are the heart of YAML automation in Home Assistant. They allow you to create dynamic responses and actions based on the state of your entities.

Imagine an automation that notifies you when a door is opened. Instead of creating a separate automation for every single door, you can use one powerful automation with template variables.

automation:
  - alias: "Door Open Notification"
    trigger:
      - platform: state
        entity_id:
          - binary_sensor.front_door
          - binary_sensor.patio_door
        to: 'on'
    action:
      - service: notify.mobile_app_my_phone
        data:
          title: "Security Alert!"
          message: "The {{ trigger.to_state.attributes.friendly_name }} was just opened."

In this example, {{ trigger.to_state.attributes.friendly_name }} is a template variable that will be replaced with the friendly name of the sensor that triggered the automation (e.g., “Front Door” or “Patio Door”). It’s a core feature of Home Assistant automations.

Environment Variables in Docker and CI/CD

Outside the smart home world, environment variables are the most common method for parameterizing configurations, especially in containerized environments with Docker.

For example, when setting up Zigbee2MQTT via Docker Compose, you can define the Zigbee coordinator’s port as an environment variable. This makes it easy to migrate your setup or change hardware without ever touching the main compose file.

Example docker-compose.yml:

version: '3.8'
services:
  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: koenkk/zigbee2mqtt
    environment:
      - TZ=${SYSTEM_TIMEZONE}
    ports:
      - 8080:8080
    devices:
      - /dev/ttyACM0:/dev/ttyACM0
    restart: unless-stopped

Here, ${SYSTEM_TIMEZONE} will be read from an .env file in the same directory or from the host OS’s environment variables, allowing for a flexible and portable setup.

Best Practices for Using YAML Variables in 2026

  • Use Descriptive Names: Choose clear names for your anchors and variables (e.g., &main_bedroom_light instead of &light1).
  • Centralize Common Values: If a value is used more than twice, make it an anchor. It’s the DRY thing to do.
  • Security First: Always use files like secrets.yaml for sensitive info. Never commit keys or passwords to a public repository!
  • Modularize Your Configs: Use directives like !include, !include_dir_list, or !include_dict to split massive YAML files into smaller, manageable parts. This is standard practice in complex Home Assistant setups.
  • Comment Your Code: Explain the purpose of complex variables. Your future self will thank you.
  • Validate Your Syntax: Before deploying, use online validators or the built-in tools in editors like Visual Studio Code to ensure your YAML syntax is correct.

Mastering variables in YAML opens up a new world of possibilities, enabling you to build robust, secure, and easy-to-maintain configurations for all your IoT and automation projects.