fd
is a program to find entries in your filesystem.
It is a simple, fast and user-friendly alternative to find
.
While it does not aim to support all of find
's powerful functionality, it provides sensible
(opinionated) defaults for a majority of use cases.
Installation • How to use • Troubleshooting
- Intuitive syntax:
fd PATTERN
instead offind -iname '*PATTERN*'
. - Regular expression (default) and glob-based patterns.
- Very fast due to parallelized directory traversal.
- Uses colors to highlight different file types (same as
ls
). - Supports parallel command execution
- Smart case: the search is case-insensitive by default. It switches to case-sensitive if the pattern contains an uppercase character*.
- Ignores hidden directories and files, by default.
- Ignores patterns from your
.gitignore
, by default. - The command name is 50% shorter* than
find
:-).
First, to get an overview of all available command line options, you can either run
fd -h
for a concise help message or fd --help
for a more detailed
version.
fd is designed to find entries in your filesystem. The most basic search you can perform is to
run fd with a single argument: the search pattern. For example, assume that you want to find an
old script of yours (the name included netflix
):
> fd netfl
Software/python/imdb-ratings/netflix-details.py
If called with just a single argument like this, fd searches the current directory recursively
for any entries that contain the pattern netfl
.
The search pattern is treated as a regular expression. Here, we search for entries that start
with x
and end with rc
:
> cd /etc
> fd '^x.*rc$'
X11/xinit/xinitrc
X11/xinit/xserverrc
The regular expression syntax used by fd
is documented here.
If we want to search a specific directory, it can be given as a second argument to fd:
> fd passwd /etc
/etc/default/passwd
/etc/pam.d/passwd
/etc/passwd
fd can be called with no arguments. This is very useful to get a quick overview of all entries
in the current directory, recursively (similar to ls -R
):
> cd fd/tests
> fd
testenv
testenv/mod.rs
tests.rs
If you want to use this functionality to list all files in a given directory, you have to use
a catch-all pattern such as .
or ^
:
> fd . fd/tests/
testenv
testenv/mod.rs
tests.rs
Often, we are interested in all files of a particular type. This can be done with the -e
(or
--extension
) option. Here, we search for all Markdown files in the fd repository:
> cd fd
> fd -e md
CONTRIBUTING.md
README.md
The -e
option can be used in combination with a search pattern:
> fd -e rs mod
src/fshelper/mod.rs
src/lscolors/mod.rs
tests/testenv/mod.rs
To find files with exactly the provided search pattern, use the -g
(or --glob
) option:
> fd -g libc.so /usr
/usr/lib32/libc.so
/usr/lib/libc.so
Hidden and ignored files
By default, fd does not search hidden directories and does not show hidden files in the
search results. To disable this behavior, we can use the -H
(or --hidden
) option:
> fd pre-commit
> fd -H pre-commit
.git/hooks/pre-commit.sample
If we work in a directory that is a Git repository (or includes Git repositories), fd does not
search folders (and does not show files) that match one of the .gitignore
patterns. To disable
this behavior, we can use the -I
(or --no-ignore
) option:
> fd num_cpu
> fd -I num_cpu
target/debug/deps/libnum_cpus-f5ce7ef99006aa05.rlib
To really search all files and directories, simply combine the hidden and ignore features to show
everything (-HI
) or use -u
/--unrestricted
.
By default, fd only matches the filename of each file. However, using the --full-path
or -p
option,
you can match against the full path.
> fd -p -g '**/.git/config'
> fd -p '.*/lesson-\d+/[a-z]+.(jpg|png)'
Instead of just showing the search results, you often want to do something with them. fd
provides two ways to execute external commands for each of your search results:
- The
-x
/--exec
option runs an external command for each of the search results (in parallel). - The
-X
/--exec-batch
option launches the external command once, with all search results as arguments.
Recursively find all zip archives and unpack them:
fd -e zip -x unzip
If there are two such files, file1.zip
and backup/file2.zip
, this would execute
unzip file1.zip
and unzip backup/file2.zip
. The two unzip
processes run in parallel
(if the files are found fast enough).
Find all *.h
and *.cpp
files and auto-format them inplace with clang-format -i
:
fd -e h -e cpp -x clang-format -i
Note how the -i
option to clang-format
can be passed as a separate argument. This is why
we put the -x
option last.
Find all test_*.py
files and open them in your favorite editor:
fd -g 'test_*.py' -X vim
Note that we use capital -X
here to open a single vim
instance. If there are two such files,
test_basic.py
and lib/test_advanced.py
, this will run vim test_basic.py lib/test_advanced.py
.
To see details like file permissions, owners, file sizes etc., you can tell fd
to show them
by running ls
for each result:
fd … -X ls -lhd --color=always
This pattern is so useful that fd
provides a shortcut. You can use the -l
/--list-details
option to execute ls
in this way: fd … -l
.
The -X
option is also useful when combining fd
with ripgrep (rg
) in order to search within a certain class of files, like all C++ source files:
fd -e cpp -e cxx -e h -e hpp -X rg 'std::cout'
Convert all *.jpg
files to *.png
files:
fd -e jpg -x convert {} {.}.png
Here, {}
is a placeholder for the search result. {.}
is the same, without the file extension.
See below for more details on the placeholder syntax.
The terminal output of commands run from parallel threads using -x
will not be interlaced or garbled,
so fd -x
can be used to rudimentarily parallelize a task run over many files.
An example of this is calculating the checksum of each individual file within a directory.
fd -tf -x md5sum > file_checksums.txt
The -x
and -X
options take a command template as a series of arguments (instead of a single string).
If you want to add additional options to fd
after the command template, you can terminate it with a \;
.
The syntax for generating commands is similar to that of GNU Parallel:
{}
: A placeholder token that will be replaced with the path of the search result (documents/images/party.jpg
).{.}
: Like{}
, but without the file extension (documents/images/party
).{/}
: A placeholder that will be replaced by the basename of the search result (party.jpg
).{//}
: The parent of the discovered path (documents/images
).{/.}
: The basename, with the extension removed (party
).
If you do not include a placeholder, fd automatically adds a {}
at the end.
For -x
/--exec
, you can control the number of parallel jobs by using the -j
/--threads
option.
Use --threads=1
for serial execution.
Sometimes we want to ignore search results from a specific subdirectory. For example, we might
want to search all hidden files and directories (-H
) but exclude all matches from .git
directories. We can use the -E
(or --exclude
) option for this. It takes an arbitrary glob
pattern as an argument:
> fd -H -E .git …
We can also use this to skip mounted directories:
> fd -E /mnt/external-drive …
.. or to skip certain file types:
> fd -E '*.bak' …
To make exclude-patterns like these permanent, you can create a .fdignore
file. They work like
.gitignore
files, but are specific to fd
. For example:
> cat ~/.fdignore
/mnt/external-drive
*.bak
Note
fd
also supports .ignore
files that are used by other programs such as rg
or ag
.
If you want fd
to ignore these patterns globally, you can put them in fd
's global ignore file.
This is usually located in ~/.config/fd/ignore
in macOS or Linux, and %APPDATA%\fd\ignore
in
Windows.
You may wish to include .git/
in your fd/ignore
file so that .git
directories, and their contents
are not included in output if you use the --hidden
option.
You can use fd
to remove all files and directories that are matched by your search pattern.
If you only want to remove files, you can use the --exec-batch
/-X
option to call rm
. For
example, to recursively remove all .DS_Store
files, run:
> fd -H '^\.DS_Store$' -tf -X rm
If you are unsure, always call fd
without -X rm
first. Alternatively, use rm
s "interactive"
option:
> fd -H '^\.DS_Store$' -tf -X rm -i
If you also want to remove a certain class of directories, you can use the same technique. You will
have to use rm
s --recursive
/-r
flag to remove directories.
Note
There are scenarios where using fd … -X rm -r
can cause race conditions: if you have a
path like …/foo/bar/foo/…
and want to remove all directories named foo
, you can end up in a
situation where the outer foo
directory is removed first, leading to (harmless) "'foo/bar/foo':
No such file or directory" errors in the rm
call.
This is the output of fd -h
. To see the full set of command-line options, use fd --help
which
also includes a much more detailed help text.
Usage: fd [OPTIONS] [pattern] [path]...
Arguments:
[pattern] the search pattern (a regular expression, unless '--glob' is used; optional)
[path]... the root directories for the filesystem search (optional)
Options:
-H, --hidden Search hidden files and directories
-I, --no-ignore Do not respect .(git|fd)ignore files
-s, --case-sensitive Case-sensitive search (default: smart case)
-i, --ignore-case Case-insensitive search (default: smart case)
-g, --glob Glob-based search (default: regular expression)
-a, --absolute-path Show absolute instead of relative paths
-l, --list-details Use a long listing format with file metadata
-L, --follow Follow symbolic links
-p, --full-path Search full abs. path (default: filename only)
-d, --max-depth <depth> Set maximum search depth (default: none)
-E, --exclude <pattern> Exclude entries that match the given glob pattern
-t, --type <filetype> Filter by type: file (f), directory (d/dir), symlink (l),
executable (x), empty (e), socket (s), pipe (p), char-device
(c), block-device (b)
-e, --extension <ext> Filter by file extension
-S, --size <size> Limit results based on the size of files
--changed-within <date|dur> Filter by file modification time (newer than)
--changed-before <date|dur> Filter by file modification time (older than)
-o, --owner <user:group> Filter by owning user and/or group
--format <fmt> Print results according to template
-x, --exec <cmd>... Execute a command for each search result
-X, --exec-batch <cmd>... Execute a command with all search results at once
-c, --color <when> When to use colors [default: auto] [possible values: auto,
always, never]
--hyperlink[=<when>] Add hyperlinks to output paths [default: never] [possible
values: auto, always, never]
-h, --help Print help (see more with '--help')
-V, --version Print version
Let's search my home folder for files that end in [0-9].jpg
. It contains ~750.000
subdirectories and about a 4 million files. For averaging and statistical analysis, I'm using
hyperfine. The following benchmarks are performed
with a "warm"/pre-filled disk-cache (results for a "cold" disk-cache show the same trends).
Let's start with find
:
Benchmark 1: find ~ -iregex '.*[0-9]\.jpg$'
Time (mean ± σ): 19.922 s ± 0.109 s
Range (min … max): 19.765 s … 20.065 s
find
is much faster if it does not need to perform a regular-expression search:
Benchmark 2: find ~ -iname '*[0-9].jpg'
Time (mean ± σ): 11.226 s ± 0.104 s
Range (min … max): 11.119 s … 11.466 s
Now let's try the same for fd
. Note that fd
performs a regular expression
search by default. The options -u
/--unrestricted
option is needed here for
a fair comparison. Otherwise fd
does not have to traverse hidden folders and
ignored paths (see below):
Benchmark 3: fd -u '[0-9]\.jpg$' ~
Time (mean ± σ): 854.8 ms ± 10.0 ms
Range (min … max): 839.2 ms … 868.9 ms
For this particular example, fd
is approximately 23 times faster than find -iregex
and about 13 times faster than find -iname
. By the way, both tools found the exact
same 546 files 😄.
Note: This is one particular benchmark on one particular machine. While we have performed a lot of different tests (and found consistent results), things might be different for you! We encourage everyone to try it out on their own. See this repository for all necessary scripts.
Concerning fd's speed, a lot of credit goes to the regex
and ignore
crates that are
also used in ripgrep (check it out!).
Remember that fd
ignores hidden directories and files by default. It also ignores patterns
from .gitignore
files. If you want to make sure to find absolutely every possible file, always
use the options -u
/--unrestricted
option (or -HI
to enable hidden and ignored files):
> fd -u …
fd
can colorize files by extension, just like ls
. In order for this to work, the environment
variable LS_COLORS
has to be set. Typically, the value
of this variable is set by the dircolors
command which provides a convenient configuration format
to define colors for different file formats.
On most distributions, LS_COLORS
should be set already. If you are on Windows or if you are looking
for alternative, more complete (or more colorful) variants, see here,
here or
here.
fd
also honors the NO_COLOR
environment variable.
A lot of special regex characters (like []
, ^
, $
, ..) are also special characters in your
shell. If in doubt, always make sure to put single quotes around the regex pattern:
> fd '^[A-Z][0-9]+$'
If your pattern starts with a dash, you have to add --
to signal the end of command line
options. Otherwise, the pattern will be interpreted as a command-line option. Alternatively,
use a character class with a single hyphen character:
> fd -- '-pattern'
> fd '[-]pattern'
Shell alias
es and shell functions can not be used for command execution via fd -x
or
fd -X
. In zsh
, you can make the alias global via alias -g myalias="…"
. In bash
,
you can use export -f my_function
to make available to child processes. You would still
need to call fd -x bash -c 'my_function "$1"' bash
. For other use cases or shells, use
a (temporary) shell script.
You can use fd to generate input for the command-line fuzzy finder fzf:
export FZF_DEFAULT_COMMAND='fd --type file'
export FZF_CTRL_T_COMMAND="$FZF_DEFAULT_COMMAND"
Then, you can type vim <Ctrl-T>
on your terminal to open fzf and search through the fd-results.
Alternatively, you might like to follow symbolic links and include hidden files (but exclude .git
folders):
export FZF_DEFAULT_COMMAND='fd --type file --follow --hidden --exclude .git'
You can even use fd's colored output inside fzf by setting:
export FZF_DEFAULT_COMMAND="fd --type file --color=always"
export FZF_DEFAULT_OPTS="--ansi"
For more details, see the Tips section of the fzf README.
rofi is a graphical launch menu application that is able to create menus by reading from stdin. Piping fd
output into rofi
s -dmenu
mode creates fuzzy-searchable lists of files and directories.
Create a case-insensitive searchable multi-select list of PDF files under your $HOME
directory and open the selection with your configured PDF viewer. To list all file types, drop the -e pdf
argument.
fd --type f -e pdf . $HOME | rofi -keep-right -dmenu -i -p FILES -multi-select | xargs -I {} xdg-open {}
To modify the list that is presented by rofi, add arguments to the fd
command. To modify the search behaviour of rofi, add arguments to the rofi
command.
The emacs package find-file-in-project can use fd to find files.
After installing find-file-in-project
, add the line (setq ffip-use-rust-fd t)
to your
~/.emacs
or ~/.emacs.d/init.el
file.
In emacs, run M-x find-file-in-project-by-selected
to find matching files. Alternatively, run
M-x find-file-in-project
to list all available files in the project.
To format the output of fd
as a file-tree you can use the tree
command with
--fromfile
:
❯ fd | tree --fromfile
This can be more useful than running tree
by itself because tree
does not
ignore any files by default, nor does it support as rich a set of options as
fd
does to control what to print:
❯ fd --extension rs | tree --fromfile
.
├── build.rs
└── src
├── app.rs
└── error.rs
On bash and similar you can simply create an alias:
❯ alias as-tree='tree --fromfile'
Note that fd
has a builtin feature for command execution with
its -x
/--exec
and -X
/--exec-batch
options. If you prefer, you can still use
it in combination with xargs
:
> fd -0 -e rs | xargs -0 wc -l
Here, the -0
option tells fd to separate search results by the NULL character (instead of
newlines). In the same way, the -0
option of xargs
tells it to read the input in this way.
... and other Debian-based Linux distributions.
If you run Ubuntu 19.04 (Disco Dingo) or newer, you can install the officially maintained package:
apt install fd-find
Note that the binary is called fdfind
as the binary name fd
is already used by another package.
It is recommended that after installation, you add a link to fd
by executing command
ln -s $(which fdfind) ~/.local/bin/fd
, in order to use fd
in the same way as in this documentation.
Make sure that $HOME/.local/bin
is in your $PATH
.
If you use an older version of Ubuntu, you can download the latest .deb
package from the
release page and install it via:
dpkg -i fd_9.0.0_amd64.deb # adapt version number and architecture
Note that the .deb packages on the release page for this project still name the executable fd
.
If you run Debian Buster or newer, you can install the officially maintained Debian package:
apt-get install fd-find
Note that the binary is called fdfind
as the binary name fd
is already used by another package.
It is recommended that after installation, you add a link to fd
by executing command
ln -s $(which fdfind) ~/.local/bin/fd
, in order to use fd
in the same way as in this documentation.
Make sure that $HOME/.local/bin
is in your $PATH
.
Note that the .deb packages on the release page for this project still name the executable fd
.
Starting with Fedora 28, you can install fd
from the official package sources:
dnf install fd-find
You can install the fd package from the official sources, provided you have the appropriate repository enabled:
apk add fd
You can install the fd package from the official repos:
pacman -S fd
You can also install fd from the AUR.
You can use the fd ebuild from the official repo:
emerge -av fd
You can install the fd package from the official repo:
zypper in fd
You can install fd
via xbps-install:
xbps-install -S fd
You can install the fd package from the official repo:
apt-get install fd
You can install the fd package from the official repo:
eopkg install fd
You can install the fd
package from Fedora Copr.
dnf copr enable tkbcopr/fd
dnf install fd
A different version using the slower malloc instead of jemalloc is also available from the EPEL8/9 repo as the package fd-find
.
You can install fd
with Homebrew:
brew install fd
… or with MacPorts:
port install fd
You can download pre-built binaries from the release page.
Alternatively, you can install fd
via Scoop:
scoop install fd
Or via Chocolatey:
choco install fd
Or via Winget:
winget install sharkdp.fd
You can install the fd package from the official repo:
guix install fd
You can use the Nix package manager to install fd
:
nix-env -i fd
You can use Flox to install fd
into a Flox environment:
flox install fd
You can install the fd-find package from the official repo:
pkg install fd-find
On Linux and macOS, you can install the fd-find package:
npm install -g fd-find
With Rust's package manager cargo, you can install fd via:
cargo install fd-find
Note that rust version 1.77.2 or later is required.
make
is also needed for the build.
The release page includes precompiled binaries for Linux, macOS and Windows. Statically-linked binaries are also available: look for archives with musl
in the file name.
git clone https://github.com/sharkdp/fd
# Build
cd fd
cargo build
# Run unit tests and integration tests
cargo test
# Install
cargo install --path .
fd
is distributed under the terms of both the MIT License and the Apache License 2.0.
See the LICENSE-APACHE and LICENSE-MIT files for license details.