# first_found – return first file found from list

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

## Synopsis

- this lookup checks a list of files and paths and returns the full path to the first combination found.
- As all lookups, when fed relative paths it will try use the current task’s location first and go up the chain to the containing role/play/include/etc’s location.
- The list of files has precedence over the paths searched. i.e, A task in a role has a ‘file1’ in the play’s relative path, this will be used, ‘file2’ in role’s relative path will not.
- Either a list of files `_terms` or a key files with a list of files is required for this plugin to operate.

## Parameters

Parameter | Choices/Defaults | Configuration | Comments
--- | --- | --- | ---
_terms - |  |  | list of file names
files - |  |  | list of file names
paths - |  |  | list of paths in which to look for the files
skip boolean | Default: "no" |  | Return an empty list if no file is found, instead of an error.

## Notes

Note

- This lookup can be used in ‘dual mode’, either passing a list of file names or a dictionary that has `files` and `paths`.

## Examples

    - name: show first existing file or ignore if none do
      debug: msg={{lookup('first_found', findme, errors='ignore')}}
      vars:
        findme:
          - "/path/to/foo.txt"
          - "bar.txt"  # will be looked in files/ dir relative to role and/or play
          - "/path/to/biz.txt"

    - name: |
            include tasks only if files exist.  Note the use of query() to return
            a blank list for the loop if no files are found.
      import_tasks: '{{ item }}'
      vars:
        params:
          files:
            - path/tasks.yaml
            - path/other_tasks.yaml
      loop: "{{ q('first_found', params, errors='ignore') }}"

    - name: |
            copy first existing file found to /some/file,
            looking in relative directories from where the task is defined and
            including any play objects that contain it
      copy: src={{lookup('first_found', findme)}} dest=/some/file
      vars:
        findme:
          - foo
          - "{{inventory_hostname}}"
          - bar

    - name: same copy but specific paths
      copy: src={{lookup('first_found', params)}} dest=/some/file
      vars:
        params:
          files:
            - foo
            - "{{inventory_hostname}}"
            - bar
          paths:
            - /tmp/production
            - /tmp/staging

    - name: INTERFACES | Create Ansible header for /etc/network/interfaces
      template:
        src: "{{ lookup('first_found', findme)}}"
        dest: "/etc/foo.conf"
      vars:
        findme:
          - "{{ ansible_virtualization_type }}_foo.conf"
          - "default_foo.conf"

    - name: read vars from first file found, use 'vars/' relative subdir
      include_vars: "{{lookup('first_found', params)}}"
      vars:
        params:
          files:
            - '{{ansible_os_distribution}}.yml'
            - '{{ansible_os_family}}.yml'
            - default.yml
          paths:
            - 'vars'

## Return Values

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

Key | Returned | Description
--- | --- | ---
_raw - |  | path to file found

## Status

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

### Authors

- Seth Vidal <skvidal@fedoraproject.org>

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.