Getting started

This page covers building, testing, and installing fd from the source checkout. For pre-built packages (Homebrew, Debian, Arch, scoop, winget, npm, etc.), see the Installation section of the project README.md.

Prerequisites

• Rust toolchain at version 1.90.0 or later. Cargo.toml declares rust-version = "1.90.0", and CI verifies this in the min_version job in .github/workflows/CICD.yml.
• GNU make for the convenience targets in Makefile (only required if you want shell completions and the man page installed via the Makefile; cargo build itself does not need it).
• On Unix targets that use the bundled allocator, no extra dependencies are required — tikv-jemallocator is vendored as a Rust dependency.

Cloning and building

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

# Debug build
cargo build

# Release build (what the Makefile uses)
cargo build --release

The release binary lands at target/release/fd. If you want to skip the tikv-jemallocator dependency (for example, on a target that has known issues with it), build without default features:

cargo build --release --no-default-features --features completions

The crate features are declared in Cargo.toml:

Feature	Default	Effect
use-jemalloc	yes	Enables the tikv-jemallocator dependency and the #[global_allocator] in src/main.rs.
completions	yes	Pulls in clap_complete and enables the --gen-completions flag.
base	—	use-jemalloc only, used for "base" builds without completions.
default	yes	use-jemalloc + completions.

Running the test suite

# Unit tests (inline `mod tests` blocks in src/) and integration tests (tests/tests.rs)
cargo test

# Run only one test by name
cargo test test_simple

# Run with all features enabled (matches the MSRV CI job)
cargo test --all-features

The integration test harness lives in tests/testenv/mod.rs. It builds the fd binary once via cargo and exposes a TestEnv helper that creates a temporary directory tree, runs the binary, and asserts on its stdout. See how-to-contribute/testing for details.

Lint and format checks

The project's CI mirrors three checks that you should run locally before opening a PR (see .github/workflows/CICD.yml):

# 1. Formatting (rustfmt). The settings live in rustfmt.toml.
cargo fmt -- --check

# 2. Clippy with warnings treated as errors (CI uses --all-features).
cargo clippy --all-targets --all-features -- -Dwarnings

# 3. Tests
cargo test --all-features

There are no other linters or static-analysis tools; rustfmt + clippy is the entire quality gate.

Installing locally

# Install into ~/.cargo/bin
cargo install --path .

# System-wide install with completions and man page (requires make)
make
sudo make install prefix=/usr/local

The Makefile builds the binary in release mode, generates bash/fish/PowerShell completions via fd --gen-completions, copies the zsh completion from contrib/completion/_fd, installs the man page from doc/fd.1, and places everything under $(prefix).

Generating shell completions on demand

# 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

--gen-completions is provided by clap_complete and is gated behind the completions feature.

Cross-compilation

Cross.toml configures pre-built cross images for cross-compiling to less-common targets (notably musl). The release pipeline in .github/workflows/CICD.yml uses these images to build the artifacts published on the GitHub Releases page.

Quick smoke test

Once you have a binary, try:

target/release/fd README       # find anything called *README*
target/release/fd -e rs main   # find Rust files matching "main"
target/release/fd -uH          # list every entry, including hidden and ignored

If the binary cannot be installed under the name fd because of a conflict with the Debian/Ubuntu fd package, the recommended workaround is to symlink fdfind to fd in ~/.local/bin. The packaged completions in contrib/completion/ cover both names.