The Complete Guide to use list in Ansible

If you’ve ever wondered how to handle multiple values in Ansible — like a group of servers, packages, or users — that’s where lists come in.

Lists let you store several items under one variable and use them in loops, filters, and other operations.

Let’s walk through how lists work in Ansible and how you can use them in real playbooks.

---

1. What Is a List?

A list in Ansible is simply a collection of items. You define it using dashes (-) or square brackets ([]).

Here’s a quick example:

fruits:
  - Apple
  - Banana
  - Orange

In this example, fruits contains three items: Apple, Banana, and Orange.

You’ll see lists like this everywhere in Ansible — because they make automation cleaner and more flexible.

---

2. Iterating Through a List

Let’s start with something practical.

Suppose you want to perform an action for each item in a list — like printing their names or copying files.

You can do that using the with_items or loop keyword.

See also: Mastering the Linux Command Line — Your Complete Free Training Guide

- name: List iteration
  debug:
    var: item
  with_items:
    - item1
    - item2
    - item3

When you run this playbook, Ansible will go through each item one by one and display its value.

It’s like saying: “Do this task for every element in my list.”

---

3. Joining Two Lists Together

Sometimes, you’ll have two lists and want to combine them.

In Ansible, you can do this using the + operator.

- name: List concatenation
  debug:
    var: my_list1 + my_list2
  vars:
    my_list1:
      - item1
      - item2
    my_list2:
      - item3
      - item4

When you run this, the two lists join together into one:

[item1, item2, item3, item4]

This is especially handy when you’re managing items from different roles or variables.

---

4. Accessing Items by Index

Let’s say you only want one specific element from a list.

You can use square brackets ([]) to access it by its index (starting from zero).

- name: List indexing
  debug:
    var: my_list[1]
  vars:
    my_list:
      - item1
      - item2
      - item3

This will display:

item2

So remember: the first item is [0], the second is [1], and so on.

---

5. Counting the Number of Items

What if you just want to know how many items are in your list?

That’s easy — you can use the length filter.

- name: List length
  debug:
    var: my_list | length
  vars:
    my_list:
      - item1
      - item2
      - item3

This will return 3.

It’s a simple but useful trick when you’re checking how many elements you’re about to loop through.

---

6. Adding a New Item to a List

Now imagine your list is growing — maybe you want to add a new item dynamically.

You can do this using the set_fact module combined with list concatenation.

- name: Append item3 to my_list
  set_fact:
    my_list: "{{ my_list + ['item3'] }}"
  vars:
    my_list:
      - item1
      - item2

After this task runs, my_list becomes:

[item1, item2, item3]

This method lets you build lists dynamically as your playbook runs.

---

7. Merging Lists Together

Sometimes, you’ll need to merge lists into a single one.

For that, you can use the combine filter.

- name: List merging
  debug:
    var: my_list1 | combine(my_list2)
  vars:
    my_list1:
      - item1
      - item2
    my_list2:
      - item3
      - item4

This will give you:

[item1, item2, item3, item4]

It’s a clean way to handle multiple variable sources at once.

---

8. Removing Items from a List

Now, what if you want to take some items out of a list?

Ansible provides the difference filter for that.

- name: List removing
  debug:
    var: my_list1 | difference(my_list2)
  vars:
    my_list1:
      - item1
      - item2
      - item3
    my_list2:
      - item2
      - item3

The result will be:

[item1]

You can think of it as “subtracting” one list from another.

---

9. Checking If an Item Exists

Before performing an action, you might want to see if something is in the list.

You can do that easily with the in keyword.

- name: Check if item2 is in my_list
  debug:
    var: "'item2' in my_list"
  vars:
    my_list:
      - item1
      - item2
      - item3

The output will be:

True

You can use this in a when condition to control when a task runs.

---

10. Filtering Items in a List

Sometimes, you only want certain items that match a condition.

You can filter them using the select filter.

- name: List filtering
  debug:
    var: my_list | select('equalto', 'item2') | list
  vars:
    my_list:
      - item1
      - item2
      - item3

The result is:

[item2]

By the way, adding | list at the end turns the result back into a normal list.

---

11. Sorting a List

Finally, you can sort lists in alphabetical or numerical order with the sort filter.

- name: List sorting
  debug:
    var: my_list | sort(reverse=true)
  vars:
    my_list:
      - item3
      - item1
      - item2

This will display:

[item3, item2, item1]

You can remove reverse=true if you want it in ascending order.

---

Wrapping Up

Lists are one of the simplest — yet most powerful — tools you’ll use in Ansible.

They help you manage groups of data, run tasks in loops, and make your playbooks much more flexible.

---

By learning how to manipulate lists, you’re opening the door to writing cleaner, smarter, and more dynamic playbooks.

Try a few of these examples in your next project — once you get the hang of it, you’ll start seeing how much time and effort lists can save you.