A variable in Home Assistant holds a value for the length of one automation or script run. When the run ends, the variable is gone. Home Assistant has no built-in global variables. If a value has to survive between runs, survive a restart, or be shared between automations, store it in a helper such as an input_number or input_text.
Where variables come from
You can define variables in three places:
- At the top level of an automation or script, under
variables:. The value applies to the whole run. - As a
variablesaction in the middle of a sequence. The value is available from that step onward. - Under
trigger_variables:, which are evaluated when the triggers are set up. These accept only limited templates and cannot read entity states.
Home Assistant also provides some values for you. In an automation started by a state change, trigger.entity_id is the entity that changed, and trigger.to_state.state is its new state.
A worked example
This automation sets the hallway light’s brightness, using a lower value at night. The night check is a single Jinja expression:
automation:
- alias: "Hallway light on motion"
mode: restart
triggers:
- trigger: state
entity_id: binary_sensor.hallway_motion
to: "on"
actions:
- variables:
target_brightness: "{{ 30 if now().hour >= 22 or now().hour < 7 else 80 }}"
- action: light.turn_on
target:
entity_id: light.hallway
data:
brightness_pct: "{{ target_brightness }}"
The mode: restart line lets new motion start a fresh run. This example only sets the brightness. For the full on-and-off pattern, see how to turn on lights with a motion sensor.
Variables appear in templates as {{ name }}. You can use them in data, in target, or inside other templates.
Scope: where changes stay
A variable’s scope is the part of a run where it can be read and changed. Older guides and forum posts describe a common problem: a variables step inside an if or choose block did not reliably change a variable in the outer sequence, and the new value could be lost when the block ended.
Recent releases changed this so that a variables step inside a nested block can update a variable from the outer scope. Check the release notes for your version before you rely on either behavior.
If you are on an older version, avoid depending on this. Work out the value in one template, as in the example above, using an inline if expression.
Persistent values with helpers
Helpers store values that survive restarts and can be changed from dashboards or other automations. Create them under Settings > Devices & services > Helpers.
| Helper | Holds | Typical use |
|---|---|---|
input_boolean |
on or off | a movie-mode override |
input_number |
a number within a range | a target temperature |
input_text |
text up to 255 characters (you set the maximum; the default is 100) | a short note |
input_select |
one option from a list | a home or away mode |
input_datetime |
a date, a time or both | the last watering time |
counter |
a count | the number of door openings |
To set a helper from a sequence, call its service:
actions:
- action: input_number.set_value
target:
entity_id: input_number.bedroom_target_temp
data:
value: 19
Helpers restore their values after a restart. Trigger-based template sensors also restore their state.
What variables cannot do
- Survive a run. A variable does not persist between runs or across restarts.
- Be shared. Another automation cannot read a variable from this one. Use a helper for that.
- Show on dashboards. Dashboard cards cannot read a variable from an automation run.
- Use entity states in trigger variables.
trigger_variablescannot read entity states. - Update themselves. A template in a
variablesstep is evaluated once, when that step runs. If you need the live value at the moment of use, put thestates()call in the action that uses it. - Hold long text in an entity state. An entity state is limited to 255 characters. Attributes do not have that limit.
Choosing the right tool
- Use a variable for a value inside a single run.
- Use a helper for a value that must last, be shared, or be changed by hand.
- Use trigger data such as
trigger.to_state.statewhen you need the value that started the run.
For the actions and flow control that variables sit inside, see the automations and actions guide. If the automation that sets a variable never runs, check its trigger first. Our troubleshooting guide covers that.