Repository files navigation

[中文][한국어]

fd is a program to find entries in your filesystem.It is a simple, fast and user-friendly alternative tofind.While it does not aim to support all offind'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 asls).
• Supportsparallel command execution
• Smart case: the search is case-insensitive by default. It switches tocase-sensitive if the pattern contains an uppercasecharacter*.
• Ignores hidden directories and files, by default.
• Ignores patterns from your.gitignore, by default.
• The command name is50% shorter* thanfind :-).

First, to get an overview of all available command line options, you can either runfd -h for a concise help message orfd --help for a more detailedversion.

fd is designed to find entries in your filesystem. The most basic search you can perform is torunfd with a single argument: the search pattern. For example, assume that you want to find anold script of yours (the name includednetflix):

> fd netflSoftware/python/imdb-ratings/netflix-details.py

If called with just a single argument like this,fd searches the current directory recursivelyfor any entries thatcontain the patternnetfl.

The search pattern is treated as a regular expression. Here, we search for entries that startwithx and end withrc:

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

The regular expression syntax used byfd isdocumented here.

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

> 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 entriesin the current directory, recursively (similar tols -R):

>cd fd/tests> fdtestenvtestenv/mod.rstests.rs

If you want to use this functionality to list all files in a given directory, you have to usea catch-all pattern such as. or^:

> fd. fd/tests/testenvtestenv/mod.rstests.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 mdCONTRIBUTING.mdREADME.md

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

> fd -e rs modsrc/fshelper/mod.rssrc/lscolors/mod.rstests/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

By default,fd does not search hidden directories and does not show hidden files in thesearch 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 notsearch folders (and does not show files) that match one of the.gitignore patterns. To disablethis behavior, we can use the-I (or--no-ignore) option:

> fd num_cpu> fd -I num_cputarget/debug/deps/libnum_cpus-f5ce7ef99006aa05.rlib

To really searchall files and directories, simply combine the hidden and ignore features to showeverything (-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 todo something with them.fdprovides two ways to execute external commands for each of your search results:

• The-x/--exec option runs an external commandfor each of the search results (in parallel).
• The-X/--exec-batch option launches the external command once, withall 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 andbackup/file2.zip, this would executeunzip file1.zip andunzip backup/file2.zip. The twounzip processes run in parallel(if the files are found fast enough).

Find all*.h and*.cpp files and auto-format them inplace withclang-format -i:

fd -e h -e cpp -x clang-format -i

Note how the-i option toclang-format can be passed as a separate argument. This is whywe put the-x option last.

Find alltest_*.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 singlevim instance. If there are two such files,test_basic.py andlib/test_advanced.py, this will runvim test_basic.py lib/test_advanced.py.

To see details like file permissions, owners, file sizes etc., you can tellfd to show themby runningls for each result:

fd … -X ls -lhd --color=always

This pattern is so useful thatfd provides a shortcut. You can use the-l/--list-detailsoption to executels in this way:fd … -l.

The-X option is also useful when combiningfd withripgrep (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,sofd -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 acommand template as a series of arguments (instead of a single string).If you want to add additional options tofd after the command template, you can terminate it with a\;.

The syntax for generating commands is similar to that ofGNU 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 mightwant to search all hidden files and directories (-H) but exclude all matches from.gitdirectories. We can use the-E (or--exclude) option for this. It takes an arbitrary globpattern 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 tofd. For example:

> cat~/.fdignore/mnt/external-drive*.bak

If you wantfd to ignore these patterns globally, you can put them infd's global ignore file.This is usually located in~/.config/fd/ignore in macOS or Linux, and%APPDATA%\fd\ignore inWindows.

You may wish to include.git/ in yourfd/ignore file so that.git directories, and their contentsare not included in output if you use the--hidden option.

You can usefd 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 callrm. Forexample, to recursively remove all.DS_Store files, run:

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

If you are unsure, always callfd without-X rm first. Alternatively, userms "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 willhave to userms--recursive/-r flag to remove directories.

This is the output offd -h. To see the full set of command-line options, usefd --help whichalso 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.000subdirectories and about a 4 million files. For averaging and statistical analysis, I'm usinghyperfine. The following benchmarks are performedwith a "warm"/pre-filled disk-cache (results for a "cold" disk-cache show the same trends).

Let's start withfind:

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 forfd. Note thatfd performs a regular expressionsearch by default. The options-u/--unrestricted option is needed here fora fair comparison. Otherwisefd does not have to traverse hidden folders andignored 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 approximately23 times faster thanfind -iregexand about13 times faster thanfind -iname. By the way, both tools found the exactsame 546 files 😄.

Note: This isone particular benchmark onone particular machine. While we haveperformed a lot of different tests (and found consistent results), things mightbe different for you! We encourage everyone to try it out on their own. Seethis repository for all necessary scripts.

Concerningfd's speed, a lot of credit goes to theregex andignore crates that arealso used inripgrep (check it out!).

Remember thatfd ignores hidden directories and files by default. It also ignores patternsfrom.gitignore files. If you want to make sure to find absolutely every possible file, alwaysuse the options-u/--unrestricted option (or-HI to enable hidden and ignored files):

> fd -u …

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

fd can colorize files by extension, just likels. In order for this to work, the environmentvariableLS_COLORS has to be set. Typically, the valueof this variable is set by thedircolors command which provides a convenient configuration formatto define colors for different file formats.On most distributions,LS_COLORS should be set already. If you are on Windows or if you are lookingfor alternative, more complete (or more colorful) variants, seehere,here orhere.

fd also honors theNO_COLOR environment variable.

A lot of special regex characters (like[],^,$, ..) are also special characters in yourshell. 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 lineoptions. 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'

Shellaliases and shell functions can not be used for command execution viafd -x orfd -X. Inzsh, you can make the alias global viaalias -g myalias="…". Inbash,you can useexport -f my_function to make available to child processes. You would stillneed to callfd -x bash -c 'my_function "$1"' bash. For other use cases or shells, usea (temporary) shell script.

You can usefd to generate input for the command-line fuzzy finderfzf:

export FZF_DEFAULT_COMMAND='fd --type file'export FZF_CTRL_T_COMMAND="$FZF_DEFAULT_COMMAND"

Then, you can typevim <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 theTips section of the fzf README.

rofi is a graphical launch menu application that is able to create menus by reading fromstdin. Pipingfd output intorofis-dmenu mode creates fuzzy-searchable lists of files and directories.

Create a case-insensitive searchable multi-select list ofPDF 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 thefd command. To modify the search behaviour of rofi, add arguments to therofi command.

The emacs packagefind-file-in-project canusefd to find files.

After installingfind-file-in-project, add the line(setq ffip-use-rust-fd t) to your~/.emacs or~/.emacs.d/init.el file.

In emacs, runM-x find-file-in-project-by-selected to find matching files. Alternatively, runM-x find-file-in-project to list all available files in the project.

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

❯ fd| tree --fromfile

This can be more useful than runningtree by itself becausetree does notignore any files by default, nor does it support as rich a set of options asfd 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 thatfd has a builtin feature forcommand execution withits-x/--exec and-X/--exec-batch options. If you prefer, you can still useit in combination withxargs:

> fd -0 -e rs| xargs -0 wc -l

Here, the-0 option tellsfd to separate search results by the NULL character (instead ofnewlines). In the same way, the-0 option ofxargs 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 theofficially maintained package:

apt install fd-find

Note that the binary is calledfdfind as the binary namefd is already used by another package.It is recommended that after installation, you add a link tofd by executing commandln -s $(which fdfind) ~/.local/bin/fd, in order to usefd 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 therelease 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 executablefd.

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

apt-get install fd-find

Note that the binary is calledfdfind as the binary namefd is already used by another package.It is recommended that after installation, you add a link tofd by executing commandln -s $(which fdfind) ~/.local/bin/fd, in order to usefd 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 executablefd.

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

dnf install fd-find

You can installthe fd packagefrom the official sources, provided you have the appropriate repository enabled:

apk add fd

You can installthe fd package from the official repos:

pacman -S fd

You can also install fdfrom the AUR.

You can usethe fd ebuild from the official repo:

emerge -av fd

You can installthe fd package from the official repo:

zypper in fd

You can installfd via xbps-install:

xbps-install -S fd

You can installthe fd package from the official repo:

apt-get install fd

You can installthe fd package from the official repo:

eopkg install fd

You can installthefd package from Fedora Copr.

dnf coprenable tkbcopr/fddnf install fd

A different version using theslower mallocinstead of jemalloc is also available from the EPEL8/9 repo as the packagefd-find.

You can installfd withHomebrew:

brew install fd

… or with MacPorts:

port install fd

You can download pre-built binaries from therelease page.

Alternatively, you can installfd viaScoop:

scoop install fd

Or viaChocolatey:

choco install fd

Or viaWinget:

winget install sharkdp.fd

You can installthe fd package from the official repo:

guix install fd

You can use theNix package manager to installfd:

nix-env -i fd

You can useFlox to installfd into a Flox environment:

flox install fd

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

pkg install fd-find

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

npm install -g fd-find

With Rust's package managercargo, you can installfd via:

cargo install fd-find

Note that rust version1.77.2 or later is required.

make is also needed for the build.

Therelease page includes precompiled binaries for Linux, macOS and Windows. Statically-linked binaries are also available: look for archives withmusl in the file name.

git clone https://github.com/sharkdp/fd# Buildcd fdcargo build# Run unit tests and integration testscargotest# Installcargo install --path.

• sharkdp
• tmccombs
• tavianator

fd is distributed under the terms of both the MIT License and the Apache License 2.0.

See theLICENSE-APACHE andLICENSE-MIT files for license details.