fzf-lua: typed prefixes, borrowed formatters and two Neovim floors
Improved fzf.vim written in lua
At a glance
- What is it?
- fzf-lua rewrites fzf.vim as a Lua module for Neovim: a curl-fed sandbox that needs no config file, pickers reachable from Lua or from the FzfLua command, a combine method that borrows the first picker's formatters, and a global window that switches entry types by typed prefix.
- Who is it for?
- fzf-lua fits editors that already run external binaries well, and it is the wrong fit for anyone who wants a picker with no fzf or skim on the machine. Check three things first: whether your Neovim is on 0.12 or only 0.9, since the README asks for both floors, whether your terminal can show images at all, and which key will own FzfLua.global().
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly Lua, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 14, 2026, and from our analysis. They are not legal advice.
Star history
- ibhagwan/fzf-lua4,496 ★ · +51
| Repository | 2026-09-23 | 2026-11-14 |
|---|---|---|
| ibhagwan/fzf-lua | 4.4k | 4.5k |
51 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The sandbox script runs the whole plugin from a remote curl
Trying fzf-lua without touching your own configuration takes one line, which pulls a script over HTTPS and pipes it into a shell that starts the plugin inside its own sandbox:
sh -c "$(curl -s https://raw.githubusercontent.com/ibhagwan/fzf-lua/main/scripts/mini.sh)"Inside that sandbox, 6 keys are wired up. `<C-\` opens buffers, `<C-p>` opens files, `<C-g>` runs grep, `<C-l>` runs live_grep, `<C-k>` lists builtin commands and `<F1>` opens the neovim help. The command ships with its own warning: the note above it calls it good practice to read the script before running `sh -c` directly from the web, so the caution about piping a remote file into a shell is written into the quickstart instead of left to the reader. Read that table as a sandbox default, though.
Two install paths ask for two different Neovim versions
The file states 2 floors for the same editor. The vim.pack snippet is introduced as working with Neovim 0.12+, while the dependency list sets the minimum at neovim 0.9 or newer. Anyone on the lower floor has a working lazy.nvim path and no vim.pack snippet at all, and the file does not say which part of the plugin needs the newer editor. A bare link to a luarocks module page sits directly above the vim.pack heading with no command underneath, so that third route is advertised without instructions. The lazy.nvim spec is the only block that shows a complete plugin spec, including `---@type fzf-lua.Config|{}` and the diagnostics switch that lets a partial table typecheck:
{
"ibhagwan/fzf-lua",
-- optional for icon support
dependencies = { "nvim-tree/nvim-web-devicons" },The icon dependency is declared twice over: nvim-tree/nvim-web-devicons is active, while nvim-mini/mini.icons sits 1 line below it commented out.
Three call syntaxes pass the same picker arguments
Every picker answers to 3 entry points that accept identical options. `:lua require("fzf-lua").files()` loads the module on demand, `FzfLua.files()` reuses the global object once it is loaded, and `:FzfLua files` is the vim command form. Arguments split the same way, with `FzfLua.files({ cwd = '~/.config' })` passing a Lua table and `:FzfLua files cwd=~/.config` passing the same value as a key=value pair. Resume follows the pattern too: `FzfLua.resume()` reopens whatever picker was closed last, and `FzfLua.files({ resume = true })` narrows that to 1 named picker. One gap stays open for anyone scripting this, since the quickstart and usage sections describe interactive invocation only and never mention a headless or non-interactive entry point.
Combine borrows the first picker's formatters and previewer
Two lists can be merged into 1 window with a single call, `FzfLua.combine({ pickers = "oldfiles;git_files" })` or `:FzfLua combine pickers=oldfiles;git_files`, where the semicolon separates picker names. The cost is that the first picker in the list donates its whole option set, and the note names formatters, previewer and path_shorten as things a later picker cannot override. The same note gives the failure mode: combine only pickers of the same entry types, files being the example used. That rule is stricter than the global picker, which mixes 3 entry types in one list on purpose, so a merged files view and a prefixed global view behave differently for a reason stated in 1 sentence.
The global picker encodes files, buffers and symbols as prefixes
One window stands in for 3 kinds of entry, and the mode is chosen by typing a character instead of calling a different command. No prefix shows files, $ shows buffers, @ shows LSP symbols for the current buffer and # shows LSP symbols for the workspace or project, 4 modes on 4 keys. It opens with `FzfLua.global()` or `:FzfLua global`. What makes this worth knowing is the entry stream: the single list holds file paths, buffer names and symbol locations together, which is the mixture the combine note refuses to build. Prefixes are what keep the streams apart, so a config that filters or reformats entries has to account for a picker holding 3 shapes at once.
Media previews wait for an extension table edit
Image previews do not arrive with the plugin. Three terminal renderers, or 3 binaries rather, are listed as optional dependencies: chafa, viu and ueberzugpp, and the note above them says they must be configured in `previewer.builtin.extensions` before they do anything. chafa carries the recommendation and the claim of supporting most file formats, while ueberzugpp is the X11/Wayland child window route covering sixels, kitty and iterm2. A 4th path needs no configuration at all: on a terminal speaking the kitty graphics protocol, such as kitty or ghostty, installing folke's snacks.nvim supplies the `snacks.image` module, which fzf-lua detects by itself. Text previews are separate again, with bat listed as the syntax highlighting layer for fzf's native previewer.
Windows needs rg and git while git-bash is optional
Two binaries are called out as Windows requirements rather than optional extras. rg is required there, and required for 2 commands specifically, `grep` and `tags`. Git for Windows is required for the git pickers, yet the note states that installing `git-bash` or sh is not required, which rules out the usual assumption that a POSIX shell has to be present. Dependency binaries, fzf, rg and fd among them, can come from 3 package managers, `scoop`, `chocolatey` or `winget-cli`. Outside those points the claim is that Windows behaves exactly as the NIX/OSX targets do, and the known issues sit in a separate README-Win.md that the main file links instead of restating.
The Makefile test target exports VIMRUNTIME twice
The test harness is where the numbers live. `nvim ?= nvim` makes the binary overridable, and the recipes accept a whole command, so 1 stable run, 1 nightly run or both in a single loop are all expressed through that variable. Modules narrow with `make test glob=file`, and the note underneath says the glob is resolved with `vim.fn.globpath`, which is why a single letter also selects every module starting with it. Screenshots regenerate by passing `update_screenshots=true` into the same run:
.PHONY: screenshots
screenshots:
make test update_screenshots=trueBefore each nvim invocation the recipe derives VIMRUNTIME, falls back to a path beside the binary when it is empty, then exports it a 2nd time alongside `FZF_LUA_NVIM_RUNTIME`. The `deps` target opens by running `make clean`, and its comment says it downloads mini.nvim and nvim-web-devicons into a deps subfolder, used only with the CI workflow.
Editorial conclusion
fzf-lua fits editors that already run external binaries well, and it is the wrong fit for anyone who wants a picker with no fzf or skim on the machine. Check three things first: whether your Neovim is on 0.12 or only 0.9, since the README asks for both floors, whether your terminal can show images at all, and which key will own FzfLua.global(). The last push to main was on 2026-11-01 and the repository has no GitHub releases.
Frequently asked questions
what is fzf lua
The project description for fzf-lua is an improved fzf.vim written in lua, a Lua rewrite of the fuzzy finder plugin that runs inside Neovim.
what does fzf-lua do
It runs fuzzy pickers over editor data: `buffers`, `files`, `oldfiles`, `history`, `quickfix`, `quickfix_stack`, `loclist`, `loclist_stack` and more, plus a global picker that combines files, buffers and LSP symbols.
how to install fzf lua
Using vim.pack requires Neovim 0.12+ and lazy.nvim is the other documented route. Dependencies are neovim 0.9 or newer, fzf above 0.36 or a skim binary, plus nvim-web-devicons or mini.icons for icons.
how to use fzf lua
Call a picker as `:lua require("fzf-lua").files()`, then use `FzfLua.files()` or the vim command once loaded, and pass options as a Lua table or as key=value pairs.
fzf lua vs fzf vim
The fzf-lua repository description is an improved fzf.vim written in lua. The file itself does not compare the two line by line and points longer documentation to the wiki linked at the top.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/ibhagwan-fzf-lua)Star history chart for your README
[](https://hysenlabs.com/projects/ibhagwan-fzf-lua)Was this useful?