- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# find – Return a list of files based on specific criteria

- Synopsis

- Parameters

- See Also

- Examples

- Return Values

- Status

## Synopsis

- Return a list of files based on specific criteria. Multiple criteria are AND’d together.

- For Windows targets, use the win_find module instead.

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
age string |  | 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 string | Choices: atime ctime mtime ← | Choose the file property against which we compare age.
contains string |  | A regular expression or pattern which should be matched against the file content.
depth integer added in 2.6 |  | Set the maximum number of levels to descend into. Setting recurse to `no` will override this value, which is effectively depth 1. Default is unlimited depth.
excludes list added in 2.5 |  | One or more (shell or regex) patterns, which type is controlled by `use_regex` option. Items whose basenames match an `excludes` pattern are culled from `patterns` matches. Multiple patterns can be specified using a list. aliases: exclude
file_type string | Choices: any directory file ← link | Type of file to select. The 'link' and 'any' choices were added in Ansible 2.3.
follow boolean | Choices: no ← yes | Set this to `yes` to follow symlinks in path for systems with python 2.6+.
get_checksum boolean | Choices: no ← yes | Set this to `yes` to retrieve a file's SHA1 checksum.
hidden boolean | Choices: no ← yes | Set this to `yes` to include hidden files, otherwise they will be ignored.
paths list / required |  | List of paths of directories to search. All paths must be fully qualified. aliases: name, path
patterns list | Default: "*" | One or more (shell or regex) patterns, which type is controlled by `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 '.*\.default' as a regexp and not just '\.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. aliases: pattern
recurse boolean | Choices: no ← yes | If target is a directory, recursively descend into the directory looking for files.
size - |  | 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 boolean | Choices: no ← yes | If `no`, the patterns are file globs (shell). If `yes`, they are python regexes.

## See Also

See also

win_find – Return a list of files based on specific criteria

  The official documentation on the win_find module.

## Examples

    - name: Recursively find /tmp files older than 2 days
      find:
        paths: /tmp
        age: 2d
        recurse: yes

    - name: Recursively find /tmp files older than 4 weeks and equal or greater than 1 megabyte
      find:
        paths: /tmp
        age: 4w
        size: 1m
        recurse: yes

    - name: Recursively find /var/tmp files with last access time greater than 3600 seconds
      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
      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
      find:
        paths: /var/log
        patterns: "^.*?\\.(?:old|log\\.gz)$"
        size: 10m
        use_regex: yes

    - name: Find /var/log all directories, exclude nginx and mysql
      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
      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
      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 | Returned | Description
--- | --- | ---
examined integer | success | Number of filesystem objects looked at Sample: 34
files list | success | All matches found with the specified criteria (see stat module for full output of each dictionary) Sample: [{'path': '/var/tmp/test1', 'mode': '0644', '...': '...', 'checksum': '16fac7be61a6e4591a33ef4b729c5c3302307523'}, {'path': '/var/tmp/test2', '...': '...'}]
matched integer | success | Number of matches Sample: 14

## Status

- This module is guaranteed to have backward compatible interface changes going forward. [stableinterface]

- This module is maintained by the Ansible Core Team. [core]

### Red Hat Support

More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.

### Authors

- Brian Coca (@bcoca)

Hint

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