Set difference: difference

The difference template function returns a list of items that are in the first list but not in the second. This is the set difference operation: it removes from the first list any items that also appear in the second list.

This is useful when you want to exclude certain items from a collection. For example, you might have all the 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] in a room and want to remove the ones that are already off, or you might have a list of all family members and want to exclude those who are currently home. You can also use it to find which devicesA device is a model representing a physical or logical unit that contains entities. have been removed from a group, or to filter out known items from a detection list. Duplicates are removed from the result since it operates as a set operation.

Usage

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

{{ difference([1, 2, 3, 4, 5], [3, 4]) }}

[1, 2, 5]

{{ [1, 2, 3, 4, 5] | difference([3, 4]) }}

[1, 2, 5]

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.

difference(
    value: list,
    other: list,
) -> list

Function parameters

The following parameters can be provided to this function.

Good to know

• Duplicates are removed in the result because this works as a set operation.
• Order is not preserved. Add | sort if you need a consistent order.
• This is one-sided. Items only in the second list do not appear in the result. Use symmetric_difference to get items unique to either side.

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.

Find entities not in a specific group

Determine which lights are in one group but not another.

{% set all_lights = expand("group.all_lights")
   | map(attribute="entity_id") | list %}
{% set automated = expand("group.automated_lights")
   | map(attribute="entity_id") | list %}
{{ difference(all_lights, automated) }}

["light.porch", "light.garage"]

Exclude unavailable entities

Filter out entities that are currently unavailable from a list.

{% set all_sensors = ["sensor.temp_a", "sensor.temp_b", "sensor.temp_c"] %}
{% set unavailable = all_sensors | select("is_state", "unavailable") | list %}
{{ difference(all_sensors, unavailable) }}

["sensor.temp_a", "sensor.temp_c"]

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:

• Set intersection: intersect - Returns items common to both lists (set intersection).

• Set union: union - Returns all unique items from both lists (set union).

• Set symmetric difference: symmetric_difference - Returns items in either list but not in both.

• Convert to set: set - Converts an iterable to a set, removing duplicate values.