---
obj: application
repo: https://github.com/sharkdp/fd
---

# fd
`fd` is a program to find entries in your filesystem. It is a simple, fast and user-friendly alternative to [`find`](https://www.gnu.org/software/findutils/). While it does not aim to support all of `find`'s powerful functionality, it provides sensible (opinionated) defaults for a majority of use cases.

## Usage
Usage: `fd [OPTIONS] [pattern] [path]...`

### Options
| Option                        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ----------------------------- |   |
| `-H, --hidden`                | Include hidden directories and files in the search results                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `-I, --no-ignore`             | Show search results from files and directories that would otherwise be ignored by `.gitignore`, `.ignore`, `.fdignore`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `-u, --unrestricted`          | Perform an unrestricted search, including ignored and hidden files. This is an alias for `--no-ignore --hidden`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `-s, --case-sensitive`        | Perform a case-sensitive search. By default, fd uses case-insensitive searches, unless the pattern contains an uppercase character (smart case).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `-i, --ignore-case`           | Perform a case-insensitive search. By default, fd uses case-insensitive searches, unless the pattern contains an uppercase character (smart case).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `-l, --list-details`          | Use a detailed listing format like `ls -l`. This is basically an alias for `--exec-batch ls -l` with some additional `ls` options. This can be used to see more metadata, to show symlink targets and to achieve a deterministic sort order.                                                                                                                                                                                                                                                                                                                                                                                                |
| `-L, --follow`                | By default, fd does not descend into symlinked directories. Using this flag, symbolic links are also traversed. Flag can be overriden with `--no-follow`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `-0, --print0`                | Separate search results by the null character (instead of newlines). Useful for piping results to `xargs`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `-d, --max-depth <depth>`     | Limit the directory traversal to a given depth. By default, there is no limit on the search depth.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `--min-depth <depth>`         | Only show search results starting at the given depth.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--exact-depth <depth>`       | Only show search results at the exact given depth. This is an alias for `--min-depth <depth> --max-depth <depth>`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `-E, --exclude <pattern>`     | Exclude files/directories that match the given glob pattern. This overrides any other ignore logic. Multiple exclude patterns can be specified.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `-t, --type <filetype>`       | Filter the search by type:<br>- `f` or `file`: regular files<br>- `d` or `directory`: directories<br>- `l` or `symlink`: symbolic links<br>- `s` or `socket`: socket<br>- `p` or `pipe`: named pipe (FIFO)<br>- `x` or `executable`: executables<br>- `e` or `empty`: empty files or directories<br><br>This option can be specified more than once to include multiple file types.                                                                                                                                                                                                                                                         |
| `-e, --extension <ext>`       | (Additionally) filter search results by their file extension. Multiple allowable file extensions can be specified.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `-S, --size <size>`           | Limit results based on the size of files using the format `<+-><NUM><UNIT>`.<br>- `+`: file size must be greater than or equal to this<br>- `-`: file size must be less than or equal to this<br>If neither `+` nor `-` is specified, file size must be exactly equal to this.                                                                                                                                                                                                                                                                                                                                                              |
| `--changed-within <date/dur>` | Filter results based on the file modification time. Files with modification times greater than the argument are returned. The argument can be provided as a specific point in time (`YYYY-MM-DD HH:MM:SS`) or as a duration (`10h`, `1d`, `35min`). If the time is not specified, it defaults to `00:00:00`. `--change-newer-than`, `--newer`, or `--changed-after` can be used as aliases.<br><br>Examples:<br>- `--changed-within 2weeks`<br>- `--change-newer-than '2018-10-27 10:00:00'`<br>- `--newer 2018-10-27`<br>- `--changed-after 1day`                                                                                          |
| `--changed-before <date/dur>` | Filter results based on the file modification time. Files with modification times less than the argument are returned.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `-o, --owner <user:group>`    | Filter files by their user and/or group. Format: `[(user/uid)][:(group/gid)]`. Either side is optional. Precede either side with a `!` to exclude files instead.<br><br>Examples:<br>- `--owner john`<br>- `--owner :students`<br>- `--owner '!john:students'`                                                                                                                                                                                                                                                                                                                                                                              |
| `-x, --exec <cmd>...`         | Execute a command for each search result in parallel (use `--threads=1` for sequential command execution). All positional arguments following `--exec` are considered to be arguments to the command - not to fd. It is therefore recommended to place the `-x`/`--exec` option last.<br><br>The following placeholders are substituted before the command is executed:<br>- `{}`: path (of the current search result)<br>- `{/}`: basename<br>- `{//}`: parent directory<br>- `{.}`: path without file extension<br>- `{/.}`: basename without file extension<br><br>If no placeholder is present, an implicit `{}` at the end is assumed. |
| `-X, --exec-batch <cmd>...`   | Execute the given command once, with all search results as arguments. One of the following placeholders is substituted before the command is executed:<br><br>- `{}`: path (of all search results)<br>- `{/}`: basename<br>- `{//}`: parent directory<br>- `{.}`: path without file extension<br>- `{/.}`: basename without file extension<br><br>If no placeholder is present, an implicit `{}` at the end is assumed.                                                                                                                                                                                                                     |
| `--batch-size <size>`         | Maximum number of arguments to pass to the command given with `-X`. If the number of results is greater than the given size, the command given with `-X` is run again with remaining arguments. A batch size of zero means there is no limit (default), but note that batching might still happen due to OS restrictions on the maximum length of command lines.                                                                                                                                                                                                                                                                            |
| `--ignore-file <path>`        | Add a custom ignore-file in `.gitignore` format. These files have a low precedence.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `-j, --threads <num>`         | Set number of threads to use for searching & executing (default: number of available CPU cores)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `--max-results <count>`       | Limit the number of search results to `count` and quit immediately.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `-1`                          | Limit the search to a single result and quit immediately. This is an alias for `--max-results=1`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `-q, --quiet`                 | When the flag is present, the program does not print anything and will return with an exit code of 0 if there is at least one match. Otherwise, the exit code will be 1.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `--one-file-system`           | By default, fd will traverse the file system tree as far as other options dictate. With this flag, fd ensures that it does not descend into a different file system than the one it started in.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
