Parse a version string: version

The version template function converts a string into a version object that can be compared with other version objects. Instead of comparing version strings as plain text (where 9.0 would incorrectly sort after 10.0), version objects understand semantic versioning and compare correctly.

This is useful when you have devicesA device is a model representing a physical or logical unit that contains entities. or software that report their firmware or software version as a sensorSensors return information about a thing, for instance the level of water in a tank. [Learn more] value. For example, you might want to check if a device’s firmware is outdated, trigger an automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [Learn more] when a new version is detected, or filter a list of devices by their version number. The version object handles common version formats like 1.2.3, 2024.1.0, and 1.0.0-beta.

Usage

Here’s how to use this template function. Copy any example and adjust it to your setup.

{{ version("2.1.0") > version("2.0.0") }}

true

{{ "2.1.0" | version > "2.0.0" | version }}

true

Function signature

The signature is a technical summary of this template function. It shows the name of the function, the values (called parameters) it accepts, and what type of data each parameter expects (for example, a piece of text or a number).

Function parameters that have a = with a value after them are optional. If you leave them out, the default value shown is used automatically. Function parameters without a default are required.

version(
    value: str,
) -> AwesomeVersion

Function parameters

The following parameters can be provided to this function.

Comparing versions

Version objects support all comparison operators. This is much safer than comparing version strings directly, because string comparison would consider 9.0 greater than 10.0.

{{ version("10.0") > version("9.0") }}

true

{{ "10.0" > "9.0" }}

false

Good to know

• Comparing two version objects returns a boolean. Comparing a version object with a plain string raises an error, so convert both sides first.
• Version parsing is lenient. Unusual formats may parse in ways you do not expect, so test your comparisons against real values.

Try it yourself

Ready to test this? Open Developer tools > Template, paste the example into the Template editor, and watch the result update on the right. Edit the values to see how the function adapts to your own entitiesAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more].

More examples

Real scenarios where this function comes up in automations and templates. Copy any example and adapt it to your setup.

Check if firmware is up to date

Compare a device’s current firmware version against the minimum required version.

{% set current = states("sensor.device_firmware") | version %}
{% set required = version("3.2.0") %}
{% if current >= required %}
  Firmware is up to date
{% else %}
  Firmware update required
{% endif %}

Firmware is up to date

Notify on version change

Detect whether a software version has increased, which could indicate an update was installed.

{{ version("2024.4.0") > version("2024.3.1") }}

true

Still stuck?

The Home Assistant community is quick to help: join Discord for real-time chat, post on the community forum with your template and expected result, or share on our subreddit /r/homeassistant.

Related template functions

These functions work well alongside this one:

• Get entity state: states - Returns the state value of an entity, or lets you iterate over all entity states.