# items – list of items

- Synopsis
- Parameters
- Notes
- Examples
- Return Values
- Status

## Synopsis

- this lookup returns a list of items given to it, if any of the top level items is also a list it will flatten it, but it will not recurse

## Parameters

Parameter | Choices/Defaults | Configuration | Comments
--- | --- | --- | ---
_terms - / required |  |  | list of items

## Notes

Note

- this is the standard lookup used for loops in most examples
- check out the ‘flattened’ lookup for recursive flattening
- if you do not want flattening nor any other transformation look at the ‘list’ lookup.

## Examples

    - name: "loop through list"
      debug:
        msg: "An item: {{ item }}"
      with_items:
        - 1
        - 2
        - 3

    - name: add several users
      user:
        name: "{{ item }}"
        groups: "wheel"
        state: present
      with_items:
         - testuser1
         - testuser2

    - name: "loop through list from a variable"
      debug:
        msg: "An item: {{ item }}"
      with_items: "{{ somelist }}"

    - name: more complex items to add several users
      user:
        name: "{{ item.name }}"
        uid: "{{ item.uid }}"
        groups: "{{ item.groups }}"
        state: present
      with_items:
         - { name: testuser1, uid: 1002, groups: "wheel, staff" }
         - { name: testuser2, uid: 1003, groups: staff }

## Return Values

Common return values are documented here, the following are the fields unique to this lookup:

Key | Returned | Description
--- | --- | ---
_raw list |  | once flattened list

## Status

- This lookup is not guaranteed to have a backwards compatible interface. [preview]
- This lookup is maintained by the Ansible Community. [community]

### Authors

- Michael DeHaan <michael.dehaan@gmail.com>

Hint

If you notice any issues in this documentation, you can edit this document to improve it.

Hint

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.