ansible.builtin.find module – Return a list of files based on specific criteria
Note
This module is part of ansible-core and included in all Ansible
installations. In most cases, you can use the short
module name
find even without specifying the collections keyword.
However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.find for easy linking to the
module documentation and to avoid conflicting with other collections that may have
the same module name.
Synopsis
Return a list of files based on specific criteria. Multiple criteria are AND’d together.
For Windows targets, use the ansible.windows.win_find module instead.
This module does not use the
findcommand, it is a much simpler and slower Python implementation. It is intended for small and simple uses. Those that need the extra power or speed and have expertise with the UNIX command, should use it directly.
Parameters
Parameter |
Comments |
|---|---|
Select files whose age is equal to or greater than the specified time. Use a negative age to find files equal to or less than the specified time. You can choose seconds, minutes, hours, days, or weeks by specifying the first letter of any of those words (e.g., “1w”). |
|
Choose the file property against which we compare age. Choices:
|
|
A regular expression or pattern which should be matched against the file content. If Works only when |
|
Set the maximum number of levels to descend into. Setting recurse to Default is unlimited depth. |
|
When doing a |
|
Restrict mode matching to exact matches only, and not as a minimum set of permissions to match. Choices:
|
|
Type of file to select. The ‘link’ and ‘any’ choices were added in Ansible 2.3. Choices:
|
|
Set this to Choices:
|
|
Set this to Choices:
|
|
Set this to Choices:
|
|
Choose objects matching a specified permission. This value is restricted to modes that can be applied using the python The mode can be provided as an octal such as |
|
List of paths of directories to search. All paths must be fully qualified. |
|
One or more (shell or regex) patterns, which type is controlled by The patterns restrict the list of files to be returned to those whose basenames match at least one of the patterns specified. Multiple patterns can be specified using a list. The pattern is matched against the file base name, excluding the directory. When using regexen, the pattern MUST match the ENTIRE file name, not just parts of it. So if you are looking to match all files ending in .default, you’d need to use This parameter expects a list, which can be either comma separated or YAML. If any of the patterns contain a comma, make sure to put them in a list to avoid splitting the patterns in undesirable ways. Defaults to Default: |
|
When doing a Setting this to This uses Choices:
|
|
If target is a directory, recursively descend into the directory looking for files. Choices:
|
|
Select files whose size is equal to or greater than the specified size. Use a negative size to find files equal to or less than the specified size. Unqualified values are in bytes but b, k, m, g, and t can be appended to specify bytes, kilobytes, megabytes, gigabytes, and terabytes, respectively. Size is not evaluated for directories. |
|
If If Choices:
|
Attributes
Attribute |
Support |
Description |
|---|---|---|
Support: full since this action does not modify the target it just executes normally during check mode |
Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped. |
|
Support: none |
Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode |
|
Platform: posix |
Target OS/families that can be operated against |
See Also
See also
- ansible.windows.win_find
Return a list of files based on specific criteria.
Examples
- name: Recursively find /tmp files older than 2 days
ansible.builtin.find:
paths: /tmp
age: 2d
recurse: yes
- name: Recursively find /tmp files older than 4 weeks and equal or greater than 1 megabyte
ansible.builtin.find:
paths: /tmp
age: 4w
size: 1m
recurse: yes
- name: Recursively find /var/tmp files with last access time greater than 3600 seconds
ansible.builtin.find:
paths: /var/tmp
age: 3600
age_stamp: atime
recurse: yes
- name: Find /var/log files equal or greater than 10 megabytes ending with .old or .log.gz
ansible.builtin.find:
paths: /var/log
patterns: '*.old,*.log.gz'
size: 10m
# Note that YAML double quotes require escaping backslashes but yaml single quotes do not.
- name: Find /var/log files equal or greater than 10 megabytes ending with .old or .log.gz via regex
ansible.builtin.find:
paths: /var/log
patterns: "^.*?\\.(?:old|log\\.gz)$"
size: 10m
use_regex: yes
- name: Find /var/log all directories, exclude nginx and mysql
ansible.builtin.find:
paths: /var/log
recurse: no
file_type: directory
excludes: 'nginx,mysql'
# When using patterns that contain a comma, make sure they are formatted as lists to avoid splitting the pattern
- name: Use a single pattern that contains a comma formatted as a list
ansible.builtin.find:
paths: /var/log
file_type: file
use_regex: yes
patterns: ['^_[0-9]{2,4}_.*.log$']
- name: Use multiple patterns that contain a comma formatted as a YAML list
ansible.builtin.find:
paths: /var/log
file_type: file
use_regex: yes
patterns:
- '^_[0-9]{2,4}_.*.log$'
- '^[a-z]{1,5}_.*log$'
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
Number of filesystem objects looked at Returned: success Sample: |
|
All matches found with the specified criteria (see stat module for full output of each dictionary) Returned: success Sample: |
|
Number of matches Returned: success Sample: |
|
skipped paths and reasons they were skipped Returned: success Sample: |