Skip to content
Get packs

Guide · Open source

How to use fzf: install, search files and history

Updated · written with AI from the project's own documentation and checked against our catalogue data

fzf is a fuzzy finder that runs in the terminal. You pipe a list into it, type a few characters, and it narrows the list to matches so you can pick one. This guide covers installing it, the basic workflow, and the shell integration that adds key bindings and fuzzy completion.

fzfjunegunn/fzf · ★ 83.9k · MIT

Quick start

  1. 1Install fzf. Run brew install fzf on macOS or Linux, or use mise use -g fzf@latest if you use mise.
  2. 2Check the binary. Confirm fzf runs from your terminal after installation.
  3. 3Add shell integration. Follow the README's setup instructions for your shell to enable key bindings and fuzzy completion.
  4. 4Pipe a list into fzf. Send any command's output to fzf and type characters to narrow the results.
  5. 5Pick a result. Select the item you want, and fzf prints it so you can use it in your command or script.
  6. 6Explore options. Read the README's Options and Search syntax sections to tune the finder.

Install fzf with Homebrew or Mise

The simplest route on macOS or Linux is Homebrew. If you use mise, it can install fzf as well. fzf is also listed in many Linux distribution package managers and on Windows through Chocolatey, Scoop, Winget and MSYS2.

brew install fzf

Set up shell integration for key bindings

Installing the binary does not by itself add key bindings or fuzzy completion. The README says to set up shell integration in your shell configuration file, with separate instructions for bash, zsh, fish and Nushell. The install script from a git clone can also add these lines for you.

  • Bash, Zsh, Fish, Nushell, Vim and Neovim integrations are included.
  • The git route runs an install script that adds lines to your shell configuration file to modify PATH and set up shell integration.
git clone --depth 1 https://github.com/junegunn/fzf.git ~/.fzf ~/.fzf/install

Use fzf to filter a list

fzf reads a list from standard input, shows it in an interactive window, and returns the item you select. Type part of the name to narrow the list, then pick a result. Because it is a simple filter, it works with any command that prints lines, such as file listings, command history or process lists.

The Examples section of the README contains more patterns of this kind. The basic idea is always the same: produce lines, pipe them to fzf, and use the selection.

  • Type a few characters to match items fuzzily.
  • Pipe any command's output into fzf to choose from it.
  • Use the display modes, such as --height or --popup, to change how the window appears.

Use key bindings in the shell

With shell integration loaded, fzf adds key bindings for the command line. The README's key bindings section describes these. Browsing command history and selecting files are the common uses. Fuzzy completion extends the Tab key for files, directories, process IDs, host names and environment variables or aliases.

  • Command history search is a common use of the integration.
  • Fuzzy completion covers files and directories, process IDs, host names and environment variables or aliases.
  • Bash and zsh completion can be customized, and fish and Nushell have their own setup sections.

Customize the look and search syntax

fzf supports a search syntax for more precise matching, environment variables for default behaviour and options for the look of the finder. The README lists these under Search syntax, Environment variables, Customizing the look and Options. Check those sections for the exact flags rather than relying on memory.

  • Search syntax and options are documented in the README.
  • Environment variables can set defaults for the finder.
  • A theme playground is linked from the README's Tips section.

What people use it for

  • Searching for a file by part of its name in a project folder.
  • Browsing previous shell commands and re-running one.
  • Building an interactive menu inside a shell script.
  • Selecting a running process by name to act on it.
  • Fuzzy selection of files inside Vim or Neovim with the plugin.

Frequently asked questions

Is fzf free to use?

fzf is released under the MIT licence, as the project's license badge and README indicate. You can read the full licence file in the repository.

What do I need to install fzf?

The source lists no prerequisites. It is distributed as a single binary, and the recommended install commands are Homebrew and Mise, with many distribution packages also available.

How do I install fzf on Windows?

The README lists Chocolatey, Scoop, Winget and MSYS2 for Windows. Each has a command, for example choco install fzf, scoop install fzf or winget install fzf.

Why does Ctrl-R not work after installing fzf?

Installing the binary does not set up shell key bindings. You need to add the shell integration line to your shell configuration file, as described in the README's shell integration section.

What are good alternatives to fzf?

The README lists comparable projects: peco, skim, television and gum. Pick one based on which features and workflow suit you.

Can fzf search large datasets?

fzf is optimized for speed and the README says it can process millions of items in milliseconds. It filters lists in memory, so it is not a full search engine for large indexed corpora.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

fzf suits command-line users who search files or history, shell script authors who want interactive menus, and Vim or Neovim users who want fuzzy selection. It is not suited to people who prefer graphical file managers, users who cannot install binaries, or anyone needing a full indexed search engine.

Install options & downloads