fzf-lua: A Lua Reimplementation of fzf.vim for Neovim

What fzf-lua Replaces and Why It Exists

fzf.vim is the original Vim plugin that integrates the fzf binary into Vim and Neovim. It is written in Vimscript and uses Vim's built-in terminal buffer approach for displaying results. As Neovim added Lua as a first-class configuration language and as the Neovim plugin ecosystem shifted toward Lua, fzf.vim's Vimscript foundation became a practical limitation for users who wanted deep Lua integration.

fzf-lua addresses this by reimplementing the fzf.vim integration entirely in Lua. The plugin communicates with the same external fzf binary, but all the Neovim-side logic, the configuration API, the command definitions, the previewers, and the picker infrastructure are written in Lua. This allows configuration through Lua tables, integration with other Lua plugins, and access to the Neovim Lua API directly.

The repository description states it is an improved fzf.vim written in Lua, and the Quickstart note quotes the fzf author calling it something you can do because you love fzf.

Installing fzf-lua with lazy.nvim

The README shows installation via lazy.nvim as the primary method:

{
  "ibhagwan/fzf-lua",
  -- optional for icon support
  dependencies = { "nvim-tree/nvim-web-devicons" },
  -- or if using mini.icons/mini.nvim
  -- dependencies = { "nvim-mini/mini.icons" },
  ---@module "fzf-lua"
  ---@type fzf-lua.Config|{}
  ---@diagnostic disable: missing-fields
  opts = {}
  ---@diagnostic enable: missing-fields
}

The required dependencies are Neovim version 0.9 or later and fzf version 0.36 or later, or alternatively skim. The nvim-web-devicons or mini.icons plugins are optional and add file type icons to picker entries.

For testing without changing your existing configuration, the README provides a sandbox script:

sh -c "$(curl -s https://raw.githubusercontent.com/ibhagwan/fzf-lua/main/scripts/mini.sh)"

The README recommends reading the script before running it via sh -c from the web. The sandbox runs with its own default keybindings: Ctrl-backslash for buffers, Ctrl-p for files, Ctrl-g for grep, Ctrl-l for live grep, Ctrl-k for builtin commands, and F1 for Neovim help.

Core Commands and What Each One Does

fzf-lua provides commands through two interfaces: the Lua API and the :FzfLua Vim command. The README documents them as equivalent:

:lua require("fzf-lua").files()
:lua FzfLua.files()
:FzfLua files

Commands in the Buffers and Files category include files (find or fd on a path), buffers (open buffers), oldfiles (opened files history), lines (open buffers lines), blines (current buffer lines), and treesitter (current buffer treesitter symbols). Commands can take arguments:

:lua FzfLua.files({ cwd = '~/.config' })
:FzfLua files cwd=~/.config

Grep commands include grep (fixed grep), live_grep (interactive grep), and their variants. LSP commands expose references, definitions, implementations, and symbol search. Git commands include git_status, git_commits, git_bcommits, and git_branches. The plugin also supports Neovim's quickfix list, location list, and spell suggestions as picker sources.

Resume allows returning to the previous picker with its last state:

:FzfLua resume
:FzfLua files resume=true

The Global Picker and the Combine Feature

fzf-lua includes a VS Code-style global picker that unifies files, buffers, and LSP symbols in a single picker with prefix-based routing. The README documents four prefix behaviors: no prefix shows files, $ shows buffers, @ shows LSP symbols for the current buffer, and # shows LSP symbols for the workspace.

:FzfLua global

The combine method merges any two or more pickers into a single list. The README gives file history and git files as an example:

:FzfLua combine pickers=oldfiles;git_files

The README notes a constraint: the first picker's options determine the formatting, previewer, and path display for the combined result. Combining pickers of different entry types, such as files and LSP symbols, produces errors. The combine feature is designed for merging pickers of the same entry type.

Optional Dependencies and Previewer Options

fzf-lua's optional dependencies extend what the previewer can show. The fd tool (a faster find replacement) and rg (ripgrep) are used when available as faster alternatives to find and grep respectively. bat provides syntax-highlighted file previews. delta provides syntax-highlighted git diff previews.

For image preview, fzf-lua supports three terminal image protocols. chafa works with most terminal emulators and supports the widest range of image formats. viu is lighter but narrower in format support. ueberzugpp uses X11 or Wayland child windows and supports sixels, kitty protocol, and iterm2 protocol. The README also notes that Folke's snacks.nvim is auto-detected by fzf-lua when running in a kitty-compatible terminal and uses the snacks.image module for rendering without additional configuration.

For Jujutsu (jj) users, fzf-lua supports jj_files and vcs_files commands when the jj binary is installed. nvim-dap integration adds Debug Adapter Protocol pickers. nvim-treesitter-context integration shows context within the previewer.

fzf-lua vs. telescope.nvim

telescope.nvim is the most common alternative cited in the fzf-lua search questions. The architectural difference is meaningful. telescope.nvim is a self-contained Neovim plugin: it implements its own fuzzy matching, its own rendering, and its own previewer entirely within Neovim's Lua API. It does not require fzf to be installed.

fzf-lua delegates matching to the external fzf binary. This means fzf-lua's matching speed and algorithm are fzf's, not Neovim's. For users who use fzf at the command line and are familiar with its scoring algorithm, fzf-lua's results will feel consistent with their shell experience. For users who have no prior fzf experience, the difference is less significant.

telescope.nvim has a larger extension ecosystem. fzf-lua covers a wide range of built-in sources but does not use the telescope extension API. Plugins that provide telescope extensions do not automatically work with fzf-lua.

Windows Support and Known Limitations

fzf-lua supports Windows, but with documented constraints. On Windows, ripgrep (rg) is required for grep and tags commands. The Windows git client is required for git commands, though git-bash is not required. The README points to the README-Win.md file for a complete list of known issues and limitations on Windows.

Dependencies on Windows can be installed through scoop, chocolatey, or winget-cli, as listed in the README. The README notes that almost everything works on Windows exactly as on Unix and macOS, but the exceptions are documented in README-Win.md rather than the main README.

The last push was on 2026-09-27. The repository is MIT licensed and has no GitHub releases; it is distributed as a plugin through plugin managers like lazy.nvim.

Editorial conclusion

fzf-lua is the right choice for a Neovim user who already uses fzf as a command-line tool and wants the same fuzzy matching algorithm inside the editor, with Lua configuration rather than Vimscript. It is not appropriate for users who want an all-in-one finder that does not depend on an external binary: telescope.nvim works without fzf installed and uses Neovim's built-in rendering pipeline, which may suit users on environments where installing fzf is inconvenient. Before installing, verify that your Neovim version is 0.9 or later and that fzf 0.36 or later is on your path. The last push was on 2026-09-27.

Frequently asked questions

Official sources

1. ibhagwan/fzf-lua on GitHub
2. Issues
3. License: MIT
4. README