Getting started

This page covers building fzf from source, running the test suites, and the install paths shipped with the repo. For end-user installation through package managers, see the top-level README.md.

Prerequisites

• Go 1.23 or newer — declared in go.mod and enforced by the build.
• Ruby 3.x and tmux — required for the integration test suite (make itest).
• bundle (RubyGems) — to install Rubocop and the test framework's dependencies (Gemfile).
• shfmt — used by shell/update.sh --check during make lint.
• zsh and fish (optional) — needed if you want to run the shell-specific integration tests.

The exact CI environment is defined in .github/workflows/linux.yml (Ubuntu 24.04, Go 1.23, Ruby 3.4.6, plus zsh fish tmux shfmt).

Building

# Build the binary for the current platform into target/
make

# Build and copy to bin/fzf
make install

# Cross-platform build via goreleaser (snapshot, no signing)
make build

The Makefile derives the version and revision strings from git (git describe --abbrev=0 and the latest commit hash on SOURCES). When building outside a git checkout, set FZF_VERSION and FZF_REVISION explicitly:

FZF_VERSION=0.72.0 FZF_REVISION=tarball make

The default build embeds the bash/zsh/fish integration scripts and the man page directly into the binary using //go:embed directives in main.go. That is how fzf --bash, fzf --man, etc. work without any external files.

Build tags

Tag	Effect
tcell	Use the tcell renderer in src/tui/tcell.go instead of the default light renderer. Required for the legacy Windows console path.
pprof	Compile in profiling support; enables --profile-cpu, --profile-mem, --profile-block, --profile-mutex flags via src/options_pprof.go.
static	Build a statically linked binary (used by goreleaser for some Linux targets).

Set tags through make:

TAGS=tcell make clean install
TAGS=pprof  make clean install

Running the tests

# Go unit tests across src/, src/algo/, src/tui/, src/util/
make test

# Ruby integration tests (run inside a tmux session)
make itest

# Single integration test
ruby test/runner.rb --name test_something

# Benchmarks under src/
make bench

# Lint (gofmt, rubocop, shellscript update check)
make lint

# Format Go code and rewrite shell scripts via shell/update.sh
make fmt

The integration suite at test/test_core.rb and friends drives a real tmux pane through the Tmux helper in test/lib/. It expects to be inside an existing tmux session — the CI workflow runs tmux new-session -d first.

Install scripts

For end users who don't go through a package manager, the repo ships two scripts in the root:

• install — POSIX shell installer that downloads the latest release binary (or builds from source if --bin is omitted) and writes shell integration snippets into ~/.fzfrc files.
• install.ps1 — Windows PowerShell equivalent.

Both are documented inline. The uninstall script reverses the changes.

Running fzf

# Pick a file under the current directory (uses the built-in walker)
fzf

# Pipe a list in
ls | fzf
git log --oneline | fzf

# Filter mode (no UI; useful in scripts)
echo -e "foo\nbar\nbaz" | fzf -f ba

# Print the embedded integration scripts
fzf --bash
fzf --zsh
fzf --fish

# Render the embedded man page
fzf --man

The --bash / --zsh / --fish outputs include both key bindings and completion. Source them in your shell rc as described in README.md.

Where to go next

• how-to-contribute/development-workflow
• how-to-contribute/testing
• Architecture overview