Skip to content

find

Collection Note

This module is part of the ansible.builtin collection. To install the collection, use:

ansible-galaxy collection install ansible.builtin
Added in version 2.0.

Synopsis

  • Return a list of files based on specific criteria. Multiple criteria are AND'd together.
  • For Windows targets, use the M(ansible.windows.win_find) module instead.
  • This module does not use the C(find) command, 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 Defaults / Choices Comments
age
str		 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").
age_stamp
str		 Default: mtime
Choices: atime, ctime, mtime		 Choose the file property against which we compare age.
checksum_algorithm
str		 Default: sha1
Choices: md5, sha1, sha224, sha256, sha384, sha512		 Algorithm to determine checksum of file.
Will throw an error if the host is unable to use specified algorithm.
The remote host has to support the hashing method specified, V(md5) can be unavailable if the host is FIPS-140 compliant.
Availability might be restricted by the target system, for example FIPS systems won't allow md5 use
Version Added: 2.19
contains
str		 A regular expression or pattern which should be matched against the file content.
If O(read_whole_file=false) it matches against the beginning of the line (uses V(re.match(\))). If O(read_whole_file=true), it searches anywhere for that pattern (uses V(re.search(\))).
Works only when O(file_type) is V(file).
depth
int		 Set the maximum number of levels to descend into.
Setting O(recurse=false) will override this value, which is effectively depth 1.
Default is unlimited depth.
Version Added: 2.6
encoding
str		 When doing a O(contains) search, determine the encoding of the files to be searched.
Version Added: 2.17
exact_mode
bool		 Default: True
 Restrict mode matching to exact matches only, and not as a minimum set of permissions to match.
Version Added: 2.16
excludes
list / elements=str		 One or more (shell or regex) patterns, which type is controlled by O(use_regex) option.
Items whose basenames match an O(excludes) pattern are culled from O(patterns) matches. Multiple patterns can be specified using a list.
Version Added: 2.5
file_type
str		 Default: file
Choices: any, directory, file, link		 Type of file to select.
The V(link) and V(any) choices were added in Ansible 2.3.
follow
bool		 Set this to V(true) to follow symlinks in path for systems with python 2.6+.
get_checksum
bool		 Whether to return a checksum of the file.
hidden
bool		 Set this to V(true) to include hidden files, otherwise they will be ignored.
limit
int		 Limit the maximum number of matching paths returned. After finding this many, the find action will stop looking.
Matches are made from the top, down (i.e. shallowest directory first).
If not set, or set to v(null), it will do unlimited matches.
Default is unlimited matches.
Version Added: 2.18
mode
raw		 Choose objects matching a specified permission. This value is restricted to modes that can be applied using the python C(os.chmod) function.
The mode can be provided as an octal such as V("0644") or as symbolic such as V(u=rw,g=r,o=r).
Version Added: 2.16
paths
list / elements=path
required		 List of paths of directories to search. All paths must be fully qualified.
From ansible-core 2.18 and onwards, the data type has changed from C(str) to C(path).
patterns
list / elements=str		 One or more (shell or regex) patterns, which type is controlled by O(use_regex) option.
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 C(.*\.default) as a regexp and not just C(\.default).
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 V(*) when O(use_regex=False), or V(.*) when O(use_regex=True).
read_whole_file
bool		 When doing a C(contains) search, determines whether the whole file should be read into memory or if the regex should be applied to the file line-by-line.
Setting this to C(true) can have performance and memory implications for large files.
This uses V(re.search(\)) instead of V(re.match(\)).
Version Added: 2.11
recurse
bool		 If target is a directory, recursively descend into the directory looking for files.
size
str		 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.
use_regex
bool		 If V(false), the patterns are file globs (shell).
If V(true), they are python regexes.

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$'

- name: Find file containing "wally" without necessarily reading all files
  ansible.builtin.find:
    paths: /var/log
    file_type: file
    contains: wally
    read_whole_file: true
    patterns: "^.*\\.log$"
    use_regex: true
    recurse: true
    limit: 1

Return Values

Key Data Type Description Returned
examined int Number of filesystem objects looked at success
files list All matches found with the specified criteria (see stat module for full output of each dictionary) success
matched int Number of matches success
skipped_paths dict skipped paths and reasons they were skipped success

Authors

  • Brian Coca (@bcoca)