ansible.builtin.first_found lookup – return first file found from list

Note

This lookup plugin is part of ansible-core and included in all Ansible installations. In most cases, you can use the short plugin name first_found 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 lookup plugin name.

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 locations of role / play / include and so on.

  • The list of files has precedence over the paths searched. For example, 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

Comments

_terms

string

A list of file names.

files

list / elements=string

A list of file names.

Default: []

paths

list / elements=string

A list of paths in which to look for the files.

Default: []

skip

boolean

When True, return an empty list when no files are matched.

This is useful when used with with_first_found, as an empty list return to with_ calls causes the calling task to be skipped.

When used as a template via lookup or query, setting skip=True will not cause the task to skip. Tasks must handle the empty list return from the template.

When False and lookup or query specifies errors=’ignore’ all errors (including no file found, but potentially others) return an empty string or an empty list respectively.

When True and lookup or query specifies errors=’ignore’, no file found will return an empty list and other potential errors return an empty string or empty list depending on the template call (in other words return values of lookup v query).

Choices:

  • no ← (default)

  • yes

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: Set _found_file to the first existing file, raising an error if a file is not found
  set_fact:
    _found_file: "{{ lookup('first_found', findme) }}"
  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: Set _found_file to the first existing file, or an empty list if no files found
  set_fact:
    _found_file: "{{ lookup('first_found', files, paths=['/extra/path'], skip=True) }}"
  vars:
    files:
      - /path/to/foo.txt
      - /path/to/bar.txt

- name: Include tasks only if one of the files exist, otherwise skip the task
  include_tasks:
    file: "{{ item }}"
  with_first_found:
    files:
     - path/tasks.yaml
     - path/other_tasks.yaml
    skip: True

- name: Include tasks only if one of the files exists, otherwise skip
  include_tasks: '{{ tasks_file }}'
  when: tasks_file != ""
  vars:
    tasks_file: "{{ lookup('first_found', files=['tasks.yaml', 'other_tasks.yaml'], 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_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

Description

_raw

list / elements=path

path to file found

Returned: success

Authors

  • Seth Vidal

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.