community.general.file_remove module – Remove files matching a pattern from a directory

Note

This module is part of the community.general collection (version 12.2.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.file_remove.

New in community.general 12.1.0

Synopsis

  • This module removes files from a specified directory that match a given pattern. The pattern can include wildcards and regular expressions.

  • By default, only files in the specified directory are removed (non-recursive). Use the recursive option to search and remove files in subdirectories.

Parameters

Parameter

Comments

file_type

string

Type of files to remove.

Choices:

  • "any": remove both files and symbolic links.

  • "file" (default): remove only regular files.

  • "link": remove only symbolic links.

path

path / required

Path to the directory where files should be removed.

This must be an existing directory.

pattern

string / required

Pattern to match files for removal.

Supports wildcards (*, ?, [seq], [!seq]) for glob-style matching.

Use use_regex=true to interpret this as a regular expression instead.

recursive

boolean

If true, search for files recursively in subdirectories.

If false, only files in the specified directory are removed.

Choices:

  • false ← (default)

  • true

use_regex

boolean

If true, pattern is interpreted as a regular expression.

If false, pattern is interpreted as a glob-style wildcard pattern.

Choices:

  • false ← (default)

  • true

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: full

Returns details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Notes

Note

  • Directories are never removed by this module, only files and optionally symbolic links.

  • This module will not follow symbolic links when recursive=true.

  • Be careful with patterns that might match many files, especially with recursive=true.

Examples

- name: Remove all log files from /var/log
  community.general.file_remove:
    path: /var/log
    pattern: "*.log"

- name: Remove all temporary files recursively
  community.general.file_remove:
    path: /tmp/myapp
    pattern: "*.tmp"
    recursive: true

- name: Remove files matching a regex pattern
  community.general.file_remove:
    path: /data/backups
    pattern: "backup_[0-9]{8}\\.tar\\.gz"
    use_regex: true

- name: Remove both files and symbolic links
  community.general.file_remove:
    path: /opt/app/cache
    pattern: "cache_*"
    file_type: any

- name: Remove all files starting with 'test_' (check mode)
  community.general.file_remove:
    path: /home/user/tests
    pattern: "test_*"
  check_mode: true

Return Values

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

Key

Description

files_count

integer

Number of files removed.

Returned: success

Sample: 2

path

string

The directory path that was searched.

Returned: success

Sample: "/var/log"

removed_files

list / elements=string

List of files that were removed.

Returned: always

Sample: ["/var/log/app.log", "/var/log/error.log"]

Authors

  • Shahar Golshani (@shahargolshani)