---

title: "Rclone Filtering" description: "Rclone filtering, includes and excludes" versionIntroduced: "v1.22"

Filtering, includes and excludes

Filter flags determine which files rclone sync, move, ls, lsl, md5sum, sha1sum, size, delete, check and similar commands apply to.

They are specified in terms of path/file name patterns; path/file lists; file age and size, or presence of a file in a directory. Bucket based remotes without the concept of directory apply filters to object key, age and size in an analogous way.

Rclone purge does not obey filters.

To test filters without risk of damage to data, apply them to rclone ls, or with the --dry-run and -vv flags.

Rclone filter patterns can only be used in filter command line options, not in the specification of a remote.

E.g. rclone copy "remote:dir*.jpg" /path/to/dir does not have a filter effect. rclone copy remote:dir /path/to/dir --include "*.jpg" does.

Important Avoid mixing any two of --include..., --exclude... or --filter... flags in an rclone command. The results may not be what you expect. Instead use a --filter... flag.

Patterns for matching path/file names

Pattern syntax {#patterns}

Here is a formal definition of the pattern syntax, examples are below.

Rclone matching rules follow a glob style:

*         matches any sequence of non-separator (/) characters
**        matches any sequence of characters including / separators
?         matches any single non-separator (/) character
[ [ ! ] { character-range } ]
          character class (must be non-empty)
{ pattern-list }
          pattern alternatives
{{ regexp }}
          regular expression to match
c         matches character c (c != *, **, ?, \, [, {, })
\c        matches reserved character c (c = *, **, ?, \, [, {, }) or character class

character-range:

c         matches character c (c != \, -, ])
\c        matches reserved character c (c = \, -, ])
lo - hi   matches character c for lo <= c <= hi

pattern-list:

pattern { , pattern }
          comma-separated (without spaces) patterns

character classes (see Go regular expression reference) include:

Named character classes (e.g. [\d], [^\d], [\D], [^\D])
Perl character classes (e.g. \s, \S, \w, \W)
ASCII character classes (e.g. [[:alnum:]], [[:alpha:]], [[:punct:]], [[:xdigit:]])

regexp for advanced users to insert a regular expression - see below for more info:

Any re2 regular expression not containing `}}`

If the filter pattern starts with a / then it only matches at the top level of the directory tree, relative to the root of the remote (not necessarily the root of the drive). If it does not start with / then it is matched starting at the end of the path/file name but it only matches a complete path element - it must match from a / separator or the beginning of the path/file.

file.jpg   - matches "file.jpg"
           - matches "directory/file.jpg"
           - doesn't match "afile.jpg"
           - doesn't match "directory/afile.jpg"
/file.jpg  - matches "file.jpg" in the root directory of the remote
           - doesn't match "afile.jpg"
           - doesn't match "directory/file.jpg"

The top level of the remote may not be the top level of the drive.

E.g. for a Microsoft Windows local directory structure

F:
├── bkp
├── data
│   ├── excl
│   │   ├── 123.jpg
│   │   └── 456.jpg
│   ├── incl
│   │   └── document.pdf

To copy the contents of folder data into folder bkp excluding the contents of subfolder exclthe following command treats F:\data and F:\bkp as top level for filtering.

rclone copy F:\data\ F:\bkp\ --exclude=/excl/**

Important Use / in path/file name patterns and not \ even if running on Microsoft Windows.

Simple patterns are case sensitive unless the --ignore-case flag is used.

Without --ignore-case (default)

potato - matches "potato"
       - doesn't match "POTATO"

With --ignore-case

potato - matches "potato"
       - matches "POTATO"

Using regular expressions in filter patterns {#regexp}

The syntax of filter patterns is glob style matching (like bash uses) to make things easy for users. However this does not provide absolute control over the matching, so for advanced users rclone also provides a regular expression syntax.

The regular expressions used are as defined in the Go regular expression reference. Regular expressions should be enclosed in {{ }}. They will match only the last path segment if the glob doesn't start with / or the whole path name if it does. Note that rclone does not attempt to parse the supplied regular expression, meaning that using any regular expression filter will prevent rclone from using directory filter rules, as it will instead check every path against the supplied regular expression(s).

Here is how the {{regexp}} is transformed into an full regular expression to match the entire path:

{{regexp}}  becomes (^|/)(regexp)$
/{{regexp}} becomes ^(regexp)$

Regexp syntax can be mixed with glob syntax, for example

*.{{jpe?g}} to match file.jpg, file.jpeg but not file.png

You can also use regexp flags - to set case insensitive, for example

*.{{(?i)jpg}} to match file.jpg, file.JPG but not file.png

Be careful with wildcards in regular expressions - you don't want them to match path separators normally. To match any file name starting with start and ending with end write

{{start[^/]*end\.jpg}}

Not

{{start.*end\.jpg}}

Which will match a directory called start with a file called end.jpg in it as the .* will match / characters.

Note that you can use -vv --dump filters to show the filter patterns in regexp format - rclone implements the glob patterns by transforming them into regular expressions.

Filter pattern examples {#examples}

How filter rules are applied to files {#how-filter-rules-work}

Rclone path/file name filters are made up of one or more of the following flags:

• --include
• --include-from
• --exclude
• --exclude-from
• --filter
• --filter-from

There can be more than one instance of individual flags.

Rclone internally uses a combined list of all the include and exclude rules. The order in which rules are processed can influence the result of the filter.

All flags of the same type are processed together in the order above, regardless of what order the different types of flags are included on the command line.

Multiple instances of the same flag are processed from left to right according to their position in the command line.

To mix up the order of processing includes and excludes use --filter... flags.

Within --include-from, --exclude-from and --filter-from flags rules are processed from top to bottom of the referenced file.

If there is an --include or --include-from flag specified, rclone implies a - ** rule which it adds to the bottom of the internal rule list. Specifying a + rule with a --filter... flag does not imply that rule.

Each path/file name passed through rclone is matched against the combined filter list. At first match to a rule the path/file name is included or excluded and no further filter rules are processed for that path/file.

If rclone does not find a match, after testing against all rules (including the implied rule if appropriate), the path/file name is included.

Any path/file included at that stage is processed by the rclone command.

--files-from and --files-from-raw flags over-ride and cannot be combined with other filter options.

To see the internal combined rule list, in regular expression form, for a command add the --dump filters flag. Running an rclone command with --dump filters and -vv flags lists the internal filter elements and shows how they are applied to each source path/file. There is not currently a means provided to pass regular expression filter options into rclone directly though character class filter rules contain character classes. Go regular expression reference

How filter rules are applied to directories {#directory_filter}

Rclone commands are applied to path/file names not directories. The entire contents of a directory can be matched to a filter by the pattern directory/* or recursively by directory/**.

Directory filter rules are defined with a closing / separator.

E.g. /directory/subdirectory/ is an rclone directory filter rule.

Rclone commands can use directory filter rules to determine whether they recurse into subdirectories. This potentially optimises access to a remote by avoiding listing unnecessary directories. Whether optimisation is desirable depends on the specific filter rules and source remote content.

If any regular expression filters are in use, then no directory recursion optimisation is possible, as rclone must check every path against the supplied regular expression(s).

Directory recursion optimisation occurs if either:

• A source remote does not support the rclone ListR primitive. local, sftp, Microsoft OneDrive and WebDAV do not support ListR. Google Drive and most bucket type storage do. Full list

• On other remotes (those that support ListR), if the rclone command is not naturally recursive, and provided it is not run with the --fast-list flag. ls, lsf -R and size are naturally recursive but sync, copy and move are not.

• Whenever the --disable ListR flag is applied to an rclone command.

Rclone commands imply directory filter rules from path/file filter rules. To view the directory filter rules rclone has implied for a command specify the --dump filters flag.

E.g. for an include rule

/a/*.jpg

Rclone implies the directory include rule

/a/

Directory filter rules specified in an rclone command can limit the scope of an rclone command but path/file filters still have to be specified.

E.g. rclone ls remote: --include /directory/ will not match any files. Because it is an --include option the --exclude ** rule is implied, and the /directory/ pattern serves only to optimise access to the remote by ignoring everything outside of that directory.

E.g. rclone ls remote: --filter-from filter-list.txt with a file filter-list.txt:

- /dir1/
- /dir2/
+ *.pdf
- **

All files in directories dir1 or dir2 or their subdirectories are completely excluded from the listing. Only files of suffix pdf in the root of remote: or its subdirectories are listed. The - ** rule prevents listing of any path/files not previously matched by the rules above.

Option exclude-if-present creates a directory exclude rule based on the presence of a file in a directory and takes precedence over other rclone directory filter rules.

When using pattern list syntax, if a pattern item contains either / or **, then rclone will not able to imply a directory filter rule from this pattern list.

E.g. for an include rule

{dir1/**,dir2/**}

Rclone will match files below directories dir1 or dir2 only, but will not be able to use this filter to exclude a directory dir3 from being traversed.

Directory recursion optimisation may affect performance, but normally not the result. One exception to this is sync operations with option --create-empty-src-dirs, where any traversed empty directories will be created. With the pattern list example {dir1/**,dir2/**} above, this would create an empty directory dir3 on destination (when it exists on source). Changing the filter to {dir1,dir2}/**, or splitting it into two include rules --include dir1/** --include dir2/**, will match the same files while also filtering directories, with the result that an empty directory dir3 will no longer be created.

--exclude - Exclude files matching pattern

Excludes path/file names from an rclone command based on a single exclude rule.

This flag can be repeated. See above for the order filter flags are processed in.

--exclude should not be used with --include, --include-from, --filter or --filter-from flags.

--exclude has no effect when combined with --files-from or --files-from-raw flags.

E.g. rclone ls remote: --exclude *.bak excludes all .bak files from listing.

E.g. rclone size remote: "--exclude /dir/**" returns the total size of all files on remote: excluding those in root directory dir and sub directories.

E.g. on Microsoft Windows rclone ls remote: --exclude "*\[{JP,KR,HK}\]*" lists the files in remote: without [JP] or [KR] or [HK] in their name. Quotes prevent the shell from interpreting the \ characters.\ characters escape the [ and ] so an rclone filter treats them literally rather than as a character-range. The { and } define an rclone pattern list. For other operating systems single quotes are required ie rclone ls remote: --exclude '*\[{JP,KR,HK}\]*'

--exclude-from - Read exclude patterns from file

Excludes path/file names from an rclone command based on rules in a named file. The file contains a list of remarks and pattern rules.

For an example exclude-file.txt:

# a sample exclude rule file
*.bak
file2.jpg

rclone ls remote: --exclude-from exclude-file.txt lists the files on remote: except those named file2.jpg or with a suffix .bak. That is equivalent to rclone ls remote: --exclude file2.jpg --exclude "*.bak".

This flag can be repeated. See above for the order filter flags are processed in.

The --exclude-from flag is useful where multiple exclude filter rules are applied to an rclone command.

--exclude-from should not be used with --include, --include-from, --filter or --filter-from flags.

--exclude-from has no effect when combined with --files-from or --files-from-raw flags.

--exclude-from followed by - reads filter rules from standard input.

--include - Include files matching pattern

Adds a single include rule based on path/file names to an rclone command.

This flag can be repeated. See above for the order filter flags are processed in.

--include has no effect when combined with --files-from or --files-from-raw flags.

--include implies --exclude ** at the end of an rclone internal filter list. Therefore if you mix --include and --include-from flags with --exclude, --exclude-from, --filter or --filter-from, you must use include rules for all the files you want in the include statement. For more flexibility use the --filter-from flag.

E.g. rclone ls remote: --include "*.{png,jpg}" lists the files on remote: with suffix .png and .jpg. All other files are excluded.

E.g. multiple rclone copy commands can be combined with --include and a pattern-list.

rclone copy /vol1/A remote:A
rclone copy /vol1/B remote:B

is equivalent to:

rclone copy /vol1 remote: --include "{A,B}/**"

E.g. rclone ls remote:/wheat --include "??[^[:punct:]]*" lists the files remote: directory wheat (and subdirectories) whose third character is not punctuation. This example uses an ASCII character class.

--include-from - Read include patterns from file

Adds path/file names to an rclone command based on rules in a named file. The file contains a list of remarks and pattern rules.

For an example include-file.txt:

# a sample include rule file
*.jpg
file2.avi

rclone ls remote: --include-from include-file.txt lists the files on remote: with name file2.avi or suffix .jpg. That is equivalent to rclone ls remote: --include file2.avi --include "*.jpg".

This flag can be repeated. See above for the order filter flags are processed in.

The --include-from flag is useful where multiple include filter rules are applied to an rclone command.

--include-from implies --exclude ** at the end of an rclone internal filter list. Therefore if you mix --include and --include-from flags with --exclude, --exclude-from, --filter or --filter-from, you must use include rules for all the files you want in the include statement. For more flexibility use the --filter-from flag.

--exclude-from has no effect when combined with --files-from or --files-from-raw flags.

--exclude-from followed by - reads filter rules from standard input.

--filter - Add a file-filtering rule

Specifies path/file names to an rclone command, based on a single include or exclude rule, in + or - format.

This flag can be repeated. See above for the order filter flags are processed in.

--filter + differs from --include. In the case of --include rclone implies an --exclude * rule which it adds to the bottom of the internal rule list. --filter...+ does not imply that rule.

--filter has no effect when combined with --files-from or --files-from-raw flags.

--filter should not be used with --include, --include-from, --exclude or --exclude-from flags.

E.g. rclone ls remote: --filter "- *.bak" excludes all .bak files from a list of remote:.

--filter-from - Read filtering patterns from a file

Adds path/file names to an rclone command based on rules in a named file. The file contains a list of remarks and pattern rules. Include rules start with + and exclude rules with - . ! clears existing rules. Rules are processed in the order they are defined.