ansible.builtin.difference filter – the difference of one list from another


This filter plugin is part of ansible-core and included in all Ansible installations. In most cases, you can use the short plugin name difference even without specifying the collections: keyword. However, we recommend you use the FQCN for easy linking to the plugin documentation and to avoid conflicting with other collections that may have the same filter plugin name.


  • Provide a unique list of all the elements of the first list that do not appear in the second one.

  • Items in the resulting list are returned in arbitrary order.


This describes the input of the filter, the value before | ansible.builtin.difference.




list / elements=string / required

A list.

Keyword parameters

This describes keyword parameters of the filter. These are the values key1=value1, key2=value2 and so on in the following example: input | ansible.builtin.difference(key1=value1, key2=value2, ...)




list / elements=string / required

A list.

See Also

See also

ansible.builtin.intersect filter plugin

intersection of lists.

ansible.builtin.symmetric_difference filter plugin

different items from two lists.

ansible.builtin.union filter plugin

union of lists.

ansible.builtin.unique filter plugin

set of unique items of a list.


# return the elements of list1 not in list2
# list1: [1, 2, 5, 1, 3, 4, 10]
# list2: [1, 2, 3, 4, 5, 11, 99]
{{ list1 | difference(list2) }}
# => [10]

Return Value



Return value

list / elements=string

A unique list of the elements from the first list that do not appear on the second.

Returned: success


  • Brian Coca (@bcoca)


Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.