Find (Unix)

find is a shell command that locates files^[1] based on search criteria and performs actions on the matching files such as printing the file system path to standard output. It starts searching at a root directory of a hierarchical structure and recursively traverses the tree although can be limited to a maximum number of levels. Commonly used search criteria include file name pattern matching and time range matching for last modification or last access. With no arguments, the command outputs the path of each file in the tree rooted at the working directory. The command can search through different file systems of partitions belonging to one or more storage devices mounted under the starting directory.^[2] The command is available on most Unix-like systems.

find
Original author	Dick Haight
Developer	AT&T Bell Laboratories
Operating system	Unix, Unix-like, Plan 9, IBM i
Platform	Cross-platform
Type	Command

Variants

The command first appeared in Version 5 Unix as part of the Programmer's Workbench project, and was written by Dick Haight alongside cpio,^[3] which were designed to be used together.^[4]

The GNU implementation was originally written by Eric Decker. It was later enhanced by David MacKenzie, Jay Plett, and Tim Wood.^[5] The GNU implementation provides features beyond the POSIX specification.

The command was ported to the IBM i operating system.^[6]

The BusyBox computer program provides the find command and many other commands in a single executable file.

Use

The syntax of the command can be described as:

$ find [-H|-L] path... [expression]

Traditionally, at least one path must precede the expression but newer versions allow for no path argument; defaulting to the working directory.

The expression can specify various aspects including match criteria and actions to perform on matched files. Expression elements are separated by whitespace and are evaluated left-to-right. The command can match via wildcard characters but wildcard match text must be quoted to prevent shell globbing. If the expression is omitted, then all files are matched.

Expression

The expression specifies the behavior of the command including what files to select (sometimes called predicate) and what to do with each matching file (sometimes called action). The elements of an expression commonly include:

-name pattern

Selects files with a name that matches a shell-glob pattern.

-type type

Selects files that are a specific Unix file type:

b: block device (buffered)

c: character device (unbuffered)

d: directory

f: regular file

l: symbolic link

p: named pipe

s: socket

D: door

-print

Prints the name of the found file plus a newline to stdout. If the expression does not contain an action option (such as -print0, -exec, or -ok) the action of -print is performed.

-print0

Prints the name of the found file plus a null character to the stdout. Not required by POSIX.

-exec program [argument...] ;

Runs a program with arguments for each candidate file; selecting files for which the program results in exit status 0. If program or an argument is {}, it is replaced with the candidate path. POSIX doesn't specify what happens if multiple {} are specified. Most implementations replace each {} with the candidate path.

-exec program [argument...] {} +

Runs a program with arguments followed by as many candidate paths as possible. Multiple commands are run if the maximum command-line size is exceeded, like for xargs).^[7]

-ok program [argument...] ;

For each candidate path, prompts the user for confirmation. If the user confirms (typically by entering y or yes), it behaves like -exec program [arguments...] ;, otherwise the command is not run for the candidate path and the file is not selected.

-maxdepth

Limits the directory depth to search. For example, -maxdepth 2 limits searching to the root directory and its direct children.

-mtime, -ctime, -atime

Modification time, inode change time and access time, respectively. Selects files with time metadata matching a number of days ago. With a + prefix, the number specifies at least and with a - prefix, the number specifies less than.

-daystart

Measure time from the beginning of a day rather than the last 24 hours.

-newer [file], -cnewer [file], -anewer [file]

Selects files more recently modified than a file. These support a -not prefix for inverse results or range.

-newermt YYYY-MM-DD

Selects files with last modified after date. Also supports a -not prefix for modified before date.

Operators

Operators are used to combine expression elements. Operators are listed in order of decreasing precedence:

Precedence

( expr ); Selects evaluation order of subexpression.

Negation

! expr; true if expr is false.

Logical and

expr1 expr2 or expr1 -a expr2; expr2 is not evaluated if expr1 is false.

Logical or

expr1 -o expr2; expr2 is not evaluated if expr1 is true.

Symbolic link traversal

In light of the fact that a file system can contain looped structures via hard and soft links, POSIX requires that the command detect infinite loops; that is, entering a previously visited directory that is an ancestor of the last file encountered. When it detects an infinite loop, the command must write a diagnostic message to standard error plus either recover its position in the hierarchy or terminate.

The -H and -L options, specified in the POSIX standard, control how the command handles symbolic links. The default behavior is to not follow symbolic links. The -L option causes the command to follow symbolic links. The -H option causes the command to follow symbolic links while processing the command line arguments.^[7] A common extension is the -P option, for explicitly disabling symlink following.^[8][9]

Examples

Search by wildcard

The following command searches the current working directory tree for files named starting with "my". The single quotes avoid the shell expansion. Without them, the shell would replace "my*" with the list of files whose names begin with "my" in the current working directory which is not necessarily the same as the files matching in subdirectories.

$ find . -name 'my*'

Limit file type

The following command includes -type f to limit results to regular files; excluding other file system items such as directories and symbolic links.

$ find . -type f

Include file detail

The following command includes the -ls action option to include detailed file information like from command ls -a.

$ find . -ls

Exclude subdirectory tree

The following command searches every directory except the subdirectory tree /not/this/one as specified by the -prune option, for a regular file named myfile.

$ find / -path /not/this/one -prune -o -type f -name myfile -print

Search multiple directories

The following command searches the dira and dirb subdirectory trees for files named myf.

$ find dira dirb -name myf

Find any one of differently named files

This following command finds files with a name ending with either "jsp" or "java" by combining two -name options with an -o option. The sub-expression (-name '*jsp' -o -name '*java') is enclosed in parentheses which are each escaped with a backslash to prevent them from being interpreted as special shell characters.

$ find . \( -name '*jsp' -o -name '*java' \)

Execute a program

The following command changes the permissions of all files with names matching "*.mp3" in the directory tree "/var/ftp/mp3". The action is specified by -exec chmod 644 {} \;. For every matching file, the command chmod 644 {} is executed by {} replaced with the name of the file. The semicolon (with backslash prefix to avoid the shell interpreting it as a command separator) indicates the end of the command. In some shells, the {} must be quoted. The trailing ; is often escaped with a leading \, but can be enclosed in single quotes instead.

$ find /var/ftp/mp3 -name '*.mp3' -type f -exec chmod 644 {} \;

Delete files

The following command deletes empty files and print the names. The -delete option is a GNU extension.

$ find . -empty -delete -print

Search by owner

The following command searches file owned by user 123.

$ find . -user 123

Ignore case

The following command matches file names ignoring case. The -iname option is not POSIX required.

$ find . -iname 'MyFile*'

If the -iname switch is not supported on your system then workaround techniques may be possible such as:

$ find . -name '[mM][yY][fF][iI][lL][eE]*'

Search by size

The following command searches for files sized between 100 kilobytes and 500 kilobytes.

$ find . -size +100k -a -size -500k

Search by time

The following command searches for files in the document folder modified in the last week.

$ find ~/Documents/ -mtime -7

The following command finds files last edited in February 2017.

$ find ~/Documents/ -newermt 2017-02-01 -not -newermt 2017-03-01

The following command lists files edited more recently than "document.txt".

$ find ~/Documents/ -newer document.txt

Related utilities

grep

A command for searching plain-text for lines matching a regular expression.

find

A command on Microsoft-based systems that although has the same name, provides significantly different functionality than the Unix-based command.

dir

A commonly-used command for listing files on Microsoft-based systems. It provides the /s option to recursively search for files or directories.

tree

A command on Microsoft-based systems that recursively lists files of a directory tree; indenting the file names according to their position in the file hierarchy.

walk and sor

Commands on Plan 9 from Bell Labs systems that provide similar functionality as find. walk finds files in a directory tree and prints the names and sor filters (like grep) by evaluating expressions in the form of a shell script. The commands are not part of Plan 9 from User Space, so Google's Benjamin Barenblat has a ported version to POSIX systems available through GitHub.^[10]

fd

An alternative to find written in Rust.^[11]

locate

A tool that searches a prebuilt database instead of the file system. The performance of locate can exceed that of find, but results can be inaccurate if the database is out-of-date. Typically, the database is updated from file system information via a find command run periodically by a cron job.

See also

• Filter (higher-order function) – Computer programming function
• find (Windows) – Shell command that finds text in files
• forfiles – Windows command that finds files by attribute, similar to Unix find
• grep – Command-line utility for text search
• List of POSIX commands
• List of DOS commands
• Spotlight (Apple) – macOS search feature