File: README.md

fd

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

Features

Intuitive syntax: fd PATTERN instead of find -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 :-).

Demo

How to use

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.

Simple search

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):

bash

> 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.

Regular expression search

The search pattern is treated as a regular expression. Here, we search for entries that start
with x and end with rc:

bash

> cd /etc
> fd '^x.*rc$'
X11/xinit/xinitrc
X11/xinit/xserverrc

The regular expression syntax used by fd is documented here.

Specifying the root directory

If we want to search a specific directory, it can be given as a second argument to fd:

bash

> fd passwd /etc
/etc/default/passwd
/etc/pam.d/passwd
/etc/passwd

List all files, recursively

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):

bash

> 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 ^:

bash

> fd . fd/tests/
testenv
testenv/mod.rs
tests.rs

Searching for a particular file extension

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:

bash

> cd fd
> fd -e md
CONTRIBUTING.md

The -e option can be used in combination with a search pattern:

bash

> fd -e rs mod
src/fshelper/mod.rs
src/lscolors/mod.rs
tests/testenv/mod.rs

Searching for a particular file name

To find files with exactly the provided search pattern, use the -g (or --glob) option:

bash

> 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:

bash

> 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:

bash

> 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.

Matching the full path

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.

bash

> fd -u -p -g '**/.git/config'
> fd -p '.*/lesson-\d+/[a-z]+.(jpg|png)'

Command execution

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.

Examples

Recursively find all zip archives and unpack them:

bash

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:

bash

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.

Any positional arguments after -x belong to the command template, not to fd itself. If you
also want to pass a pattern or search path, put -x last:

bash

fd pattern path -x echo

Find all test_*.py files and open them in your favorite editor:

bash

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:

bash

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:

bash

fd -e cpp -e cxx -e h -e hpp -X rg 'std::cout'

Convert all *.jpg files to *.png files:

bash

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.

bash

fd -tf -x md5sum > file_checksums.txt

Placeholder syntax

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 \;.

For example, fd -x echo \; pattern path treats pattern path as fd arguments instead of
passing them to echo. In practice, it is often clearer to write fd pattern path -x echo.

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.

Parallel vs. serial execution

For -x/--exec, you can control the number of parallel jobs by using the -j/--threads option.
Use --threads=1 for serial execution.

Excluding specific files or directories

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:

bash

> fd -H -E .git …

We can also use this to skip mounted directories:

bash

> fd -E /mnt/external-drive …

.. or to skip certain file types:

bash

> 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:

bash

> 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.

Deleting files

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:

bash

> fd -H '^\.DS_Store$' -tf -X rm

If you are unsure, always call fd without -X rm first. Alternatively, use rms "interactive"
option:

bash

> 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 rms --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.

Command-line options

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.

text

/* Detailed source-code truncated for AI context efficiency. */

Note that options can be given after the pattern and/or path as well.

Benchmark

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:

text

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:

text

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):

text

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 :smile:.

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!).

Troubleshooting

`fd` does not find my file!

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):

bash

> fd -u …

Also remember that by default, fd only searches based on the filename and
doesn't compare the pattern to the full path. If you want to search based on the
full path (similar to the -path option of find) you need to use the --full-path
(or -p) option.

Colorized output

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.

`fd` doesn't seem to interpret my regex pattern correctly

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:

bash

> 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:

bash

> fd -- '-pattern'
> fd '[-]pattern'

"Command not found" for `alias`es or shell functions

Shell aliases 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.

Placeholders in `-x`/`-X`

Depending on your shell, you may need to quote the placeholders ({}, {/}, {//},
{.}, {/.}) to prevent the shell from interpreting them before fd sees them.

Integration with other programs

Using fd with `fzf`

You can use fd to generate input for the command-line fuzzy finder fzf:

bash

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):

bash

export FZF_DEFAULT_COMMAND='fd --type file --follow --hidden --exclude .git'

You can even use fd's colored output inside fzf by setting:

bash

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.

Using fd with `rofi`

rofi is a graphical launch menu application that is able to create menus by reading from stdin. Piping fd output into rofis -dmenu mode creates fuzzy-searchable lists of files and directories.

Example

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.

bash

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.

Using fd with `emacs`

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.

Printing the output as a tree

To format the output of fd as a file-tree you can use the tree command with
--fromfile:

bash

❯ 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:

bash

❯ fd --extension rs | tree --fromfile
.
├── build.rs
└── src
    ├── app.rs
    └── error.rs

On bash and similar you can simply create an alias:

bash

❯ alias as-tree='tree --fromfile'

Using fd with `xargs` or `parallel`

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:

bash

> 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.

Installation

On Ubuntu

... and other Debian-based Linux distributions.

If you run Ubuntu 19.04 (Disco Dingo) or newer, you can install the
officially maintained package:

text

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:

bash

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.

On Debian

If you run Debian Buster or newer, you can install the
officially maintained Debian package:

text

apt-get install fd-find

Note that the .deb packages on the release page for this project still name the executable fd.

On Fedora

Starting with Fedora 28, you can install fd from the official package sources:

bash

dnf install fd-find

On Alpine Linux

You can install the fd package
from the official sources, provided you have the appropriate repository enabled:

text

apk add fd

On Arch Linux

You can install the fd package from the official repos:

text

pacman -S fd

You can also install fd from the AUR.

On Gentoo Linux

You can use the fd ebuild from the official repo:

text

emerge -av fd

On openSUSE Linux

You can install the fd package from the official repo:

text

zypper in fd

On Void Linux

You can install fd via xbps-install:

text

xbps-install -S fd

On ALT Linux

You can install the fd package from the official repo:

text

apt-get install fd

On Solus

You can install the fd package from the official repo:

text

eopkg install fd

On RedHat Enterprise Linux (RHEL) 8/9/10, Almalinux 8/9/10, EuroLinux 8/9 or Rocky Linux 8/9/10

You can install the fd package from Fedora Copr.

bash

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.

On macOS

You can install fd with Homebrew:

text

brew install fd

… or with MacPorts:

text

port install fd

On Windows

You can download pre-built binaries from the release page.

Alternatively, you can install fd via Scoop:

text

scoop install fd

Or via Chocolatey:

text

choco install fd

Or via Winget:

text

winget install sharkdp.fd

On GuixOS

You can install the fd package from the official repo:

text

guix install fd

On Mise

You can use mise to install fd with a command like this:

text

mise use -g fd@latest

On NixOS / via Nix

You can use the Nix package manager to install fd:

text

nix-env -i fd

Via Flox

You can use Flox to install fd into a Flox environment:

text

flox install fd

On FreeBSD

You can install the fd-find package from the official repo:

text

pkg install fd-find

From npm

On Linux and macOS, you can install the fd-find package:

text

npm install fd-find

From source

With Rust's package manager cargo, you can install fd via:

text

cargo install fd-find

Note that rust version 1.90.0 or later is required.

make is also needed for the build.

From binaries

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.

Development

bash

git clone https://github.com/sharkdp/fd

# Build
cd fd
cargo build

# Run unit tests and integration tests
cargo test

# Install
cargo install --path .

Completions

From Release Archives

Pre-built completion files are included in the release archives (.tar.gz/.zip) on the
Releases page, in the autocomplete directory.
To use these completions:

bash: Source the fd.bash file in your ~/.bashrc, or place it in a directory that gets sourced automatically.
zsh: Move _fd to a directory in your fpath (e.g., ~/.zfunc).
fish: Copy fd.fish to ~/.config/fish/completions/.
powershell: Source _fd.ps1 from one of your profile scripts.

Generate from fd

You can also generate completions directly using fd --gen-completions <shell>:

bash

# Bash
fd --gen-completions bash > ~/.local/share/bash-completion/completions/fd

# Zsh (ensure ~/.zfunc is in your fpath)
fd --gen-completions zsh > ~/.zfunc/_fd

# Fish
fd --gen-completions fish > ~/.config/fish/completions/fd.fish

# PowerShell
fd --gen-completions powershell >> $PROFILE

Maintainers

License

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.

File: doc/release-checklist.md

Release checklist

This file can be used as-is, or copied into the GitHub PR description which includes
necessary changes for the upcoming release.

Version bump

This section can be done by running scripts/version-bump.sh with the new version
as an argument.

Create a new branch for the required changes for this release.
Update version in Cargo.toml. Run cargo build to update Cargo.lock.
Make sure to git add the Cargo.lock changes as well.
Find the current min. supported Rust version by running
grep rust-version Cargo.toml.
Update the fd version and the min. supported Rust version in README.md.
Update CHANGELOG.md. Change the heading of the "Upcoming release" section
to the version of this release.

Pre-release checks and updates

Install the latest version (cargo install --locked -f --path .) and make
sure that it is available on the PATH (fd --version should show the
new version).
Review -h, --help, and the man page.
Run fd -h and copy the output to the "Command-line options" section in
the README. This can be done by running gawk -i inplace -f scripts/update-help.awk README.md.
Push all changes and wait for CI to succeed (before continuing with the
next section).
Optional: manually test the new features and command-line options described
in the CHANGELOG.md.
Run cargo publish --dry-run to make sure that it will succeed later
(after creating the GitHub release).

Release

Merge your release branch (should be a fast-forward merge).
Create a tag and push it: git tag vX.Y.Z; git push origin tag vX.Y.Z.
This will trigger the deployment via GitHub Actions.
REMINDER: If your origin is a fork, don't forget to push to e.g. upstream
instead.
Go to https://github.com/sharkdp/fd/releases/new to create the new
release. Select the new tag and also use it as the release title. For the
release notes, copy the corresponding section from CHANGELOG.md and
possibly add additional remarks for package maintainers.
Publish the release.
Check if the binary deployment works (archives and Debian packages should
appear when the CI run for the Git tag has finished).
Publish to crates.io by running cargo publish in a clean repository.
One way to do this is to clone a fresh copy.

Post-release

Prepare a new "Upcoming release" section at the top of CHANGELOG.md.
Put this at the top:

# Upcoming release

## Features

## Bugfixes

## Changes

## Other

File: README.md Copy Chapter

fd

Features Copy Chapter

Demo Copy Chapter

How to use Copy Chapter

Simple search Copy Section

Regular expression search Copy Section

Specifying the root directory Copy Section

List all files, recursively Copy Section

Searching for a particular file extension Copy Section

Searching for a particular file name Copy Section

Hidden and ignored files Copy Section

Matching the full path Copy Section

Command execution Copy Section

Examples

Placeholder syntax

Parallel vs. serial execution

Excluding specific files or directories Copy Section

Deleting files Copy Section

Command-line options Copy Section

Benchmark Copy Chapter

Troubleshooting Copy Chapter

`fd` does not find my file! Copy Section

Colorized output Copy Section

`fd` doesn't seem to interpret my regex pattern correctly Copy Section

"Command not found" for `alias`es or shell functions Copy Section

Placeholders in `-x`/`-X` Copy Section

Integration with other programs Copy Chapter

Using fd with `fzf` Copy Section

Using fd with `rofi` Copy Section

Example

Using fd with `emacs` Copy Section

Printing the output as a tree Copy Section

Using fd with `xargs` or `parallel` Copy Section

Installation Copy Chapter

On Ubuntu Copy Section

On Debian Copy Section

On Fedora Copy Section

On Alpine Linux Copy Section

On Arch Linux Copy Section

On Gentoo Linux Copy Section

On openSUSE Linux Copy Section

On Void Linux Copy Section

On ALT Linux Copy Section

On Solus Copy Section

On RedHat Enterprise Linux (RHEL) 8/9/10, Almalinux 8/9/10, EuroLinux 8/9 or Rocky Linux 8/9/10 Copy Section

On macOS Copy Section

On Windows Copy Section

On GuixOS Copy Section

On Mise Copy Section

On NixOS / via Nix Copy Section

Via Flox Copy Section

On FreeBSD Copy Section

From npm Copy Section

From source Copy Section

From binaries Copy Section

Development Copy Chapter

Completions Copy Section

From Release Archives

Generate from fd

Maintainers Copy Chapter

License Copy Chapter

File: doc/release-checklist.md Copy Chapter

Release checklist

Version bump Copy Chapter

Pre-release checks and updates Copy Chapter

Release Copy Chapter

Post-release Copy Chapter

File: doc/sponsors.md Copy Chapter

Sponsors Copy Chapter

Explore Related Technologies & Topics

File: README.md

Features

Demo

How to use

Simple search

Regular expression search

Specifying the root directory

List all files, recursively

Searching for a particular file extension

Searching for a particular file name

Hidden and ignored files

Matching the full path

Command execution

Excluding specific files or directories

Deleting files

Command-line options

Benchmark

Troubleshooting

`fd` does not find my file!

Colorized output

`fd` doesn't seem to interpret my regex pattern correctly

"Command not found" for `alias`es or shell functions

Placeholders in `-x`/`-X`

Integration with other programs

Using fd with `fzf`

Using fd with `rofi`

Using fd with `emacs`

Printing the output as a tree

Using fd with `xargs` or `parallel`

Installation

On Ubuntu

On Debian

On Fedora

On Alpine Linux

On Arch Linux

On Gentoo Linux

On openSUSE Linux

On Void Linux

On ALT Linux

On Solus

On RedHat Enterprise Linux (RHEL) 8/9/10, Almalinux 8/9/10, EuroLinux 8/9 or Rocky Linux 8/9/10

On macOS

On Windows

On GuixOS

On Mise

On NixOS / via Nix

Via Flox

On FreeBSD

From npm

From source

From binaries

Development

Completions

Maintainers

License

File: doc/release-checklist.md

Version bump

Pre-release checks and updates

Release

Post-release

File: doc/sponsors.md

Sponsors