telescope-fzf-native.nvim Setup and fzf Search

Why telescope-fzf-native.nvim Exists in Telescope

telescope-fzf-native.nvim replaces Telescope's generic and file sorting behavior with a C port of the algorithm used by fzf. It is intended for Telescope users who want richer search expressions than basic fuzzy matching alone. The extension is not a separate fuzzy finder interface. It acts as a Telescope extension and sorter.

Its main distinction is support for the fzf search syntax listed in the README. An unquoted term can perform a fuzzy match, a quoted term requests an exact substring match, and caret or dollar signs constrain a match to a prefix or suffix. Prefixing an exact-match expression with an exclamation mark reverses that condition. A single bar separates alternatives, so `^core go$ | rb$ | py$` searches for entries beginning with `core` and ending with one of three extensions.

This syntax makes the extension relevant when query precision matters, such as narrowing a file picker to Go, Ruby, or Python files while retaining a shared path prefix. It also offers an alternative to the simpler fzy algorithm available to Telescope through native and Lua implementations. The project does not provide binaries, so adoption means accepting a source build with CMake or make rather than installing a self-contained library.

The C Scoring Path Behind Telescope Results

The repository centers its implementation on `src/fzf.c` and `src/fzf.h`. Both supported build paths compile a shared library, with the platform-specific output named `libfzf.so` outside Windows or `libfzf.dll` on Windows. The Lua directory provides bindings and Telescope integration, while the test directory contains C and Neovim-oriented test entry points.

The scoring model separates pattern parsing from item evaluation. The C interface creates a default slab, parses a pattern with a case mode and a fuzzy-matching flag, then passes an individual line to scoring or position calculation. A parsed pattern can be reused for many items. Returned positions must be released with `fzf_free_positions`, while the pattern and slab have their own cleanup functions. The Lua interface follows the same resource model through `fzf_lib`: `allocate_slab` creates a slab, `parse_pattern` creates the reusable pattern object, and `get_score` evaluates a line. Lua positions are returned as a table and do not require explicit position cleanup.

The Makefile shows the practical build shape. Its main target compiles `src/fzf.c` with optimization and produces a shared library under `build`. The Telescope extension depends on that native component being available and then loads it through Telescope. This C-backed path is the reason the extension is described as an fzf sorter written in C, but the README explicitly limits its scope to the algorithm and the functions needed to calculate scores.

Building the Native Library with make

The shortest documented installation uses make on Linux, macOS, or Windows with MinGW. The build requires `gcc` or `clang` plus `make`. With lazy.nvim, the plugin declaration can compile the library during plugin installation. The following configuration should be placed in the Neovim plugin specification:

{ 'nvim-telescope/telescope-fzf-native.nvim', build = 'make' }

The command compiles `src/fzf.c` and writes the platform-specific shared library under the repository's `build` directory. The repository does not publish release artifacts, so a successful local compilation is part of installation rather than an optional optimization. On Windows, the Makefile sets the compiler to `gcc` and the target library to `libfzf.dll`. For systems without MinGW or an MSYS-compatible environment, the README directs Windows users toward the CMake route instead.

Developers can also use the build declarations documented for vim-plug and packer.nvim. The repository defines `clean` and `debug` targets, but these are maintenance commands rather than required first-use steps. A failed build should be resolved by checking the required compiler and make availability before moving on to Telescope configuration.

Installing telescope-fzf-native.nvim with CMake

CMake is the documented alternative and is also the route listed for Windows, Linux, and macOS. On Windows it requires CMake and the Microsoft C++ Build Tools. On Linux and macOS it requires CMake, make, and GCC or Clang. The lazy.nvim declaration passes the build command directly to the plugin manager:

{ 'nvim-telescope/telescope-fzf-native.nvim', build = 'cmake -S. -Bbuild -DCMAKE_BUILD_TYPE=Release && cmake --build build --config Release --target install' }

This command configures the `build` directory in Release mode, compiles the project, and invokes its CMake install target. The README presents equivalent declarations for vim-plug and packer.nvim, using `do` or `run` respectively. No hard-coded installation path for the resulting library appears in the README, so users should avoid assuming one from another native-plugin setup.

The choice between CMake and make is primarily about the available local toolchain. The project says both methods will be supported going forward. It does not document precompiled binaries, package-manager releases, or GitHub releases, which means the extension currently presents a source-compilation decision at installation time.

Loading the fzf Extension in Telescope

After the library has been built, Telescope must be configured to load the extension. The README says the options shown are defaults and that loading is the important part. A minimal setup can retain those defaults and then call `load_extension('fzf')` after `setup`:

require('telescope').setup {
  extensions = {
    fzf = {
      fuzzy = true,                    -- false will only do exact matching
      override_generic_sorter = true,  -- override the generic sorter
      override_file_sorter = true,     -- override the file sorter
      case_mode = "smart_case",        -- or "ignore_case" or "respect_case"
                                       -- the default case_mode is "smart_case"
    }
  }
}
-- To get fzf loaded and working with telescope, you need to call
-- load_extension, somewhere after setup function:
require('telescope').load_extension('fzf')

With `fuzzy = true`, matching uses fuzzy behavior; setting it to false limits matching to exact matching. The two override options replace Telescope's generic and file sorters by default. The documented case modes are `smart_case`, `ignore_case`, and `respect_case`, with `smart_case` as the default. The extension must be loaded after setup.

For a first picker search, open a normal Telescope picker after startup and enter a query such as `^core go$`. The reader should check whether displayed results follow the prefix, suffix, and fuzzy constraints described in the README. That first use depends on Telescope itself already being available, although this repository does not document Telescope's installation commands.

Search Operators That Differ from Basic Fuzzy Matching

The query language gives this extension more control than an undifferentiated fuzzy search. `sbtrkt` is documented as a fuzzy match against that sequence. Quoting a term, as in `'wild`, requests an exact substring. `^music` requires the entry to start with `music`, while `.mp3$` requires it to end with `.mp3`. The inverse operators `!fire`, `!^music`, and `!.mp3$` reject entries containing, beginning with, or ending with the specified text.

Alternation uses a single bar character. The README's `^core go$ | rb$ | py$` example combines a prefix condition with three possible suffix conditions. This is more expressive than merely typing several characters into a picker, but it also makes operator behavior relevant to users. The README describes the forms and the OR operator, yet it does not provide a full grammar for edge-case combinations. Complex queries should therefore be checked against the project's tests or avoided when exact fzf behavior is mandatory.

Case handling is configurable, but the scope is narrower than the name `fzf` might suggest. The TODO lists Unicode case handling as missing and says it does not currently work. Normalization is also marked as missing, and the C interface says the normalization argument must always be false because it is not implemented. These are not minor configuration details for international text or canonicalized strings, because they define a boundary in matching behavior.

Compatibility Gaps Against Full fzf

The README includes a clear disclaimer: this project implements the fzf algorithm in C, so matching may differ, and completeness is not guaranteed. That statement matters more than the project's repository name. It is not intended to reproduce every fzf feature, and its own TODO identifies two concrete omissions, normalize and Unicode case handling. Users comparing results with fzf should not assume identical output for all inputs.

The Makefile also exposes a narrower operational model than a full fzf executable. It builds a shared scoring library rather than a standalone interactive fzf binary. Developers can call the C or Lua interfaces directly, but that is a different use case from installing the Telescope extension.

The repository has no GitHub releases, so release-based upgrade planning is not documented. Its license is MIT, and the README credits the fzf algorithm to junegunn and describes this repository as a C fork distributed under MIT for Telescope. The license permits use and modification under its terms, but organizations still need to review the actual `LICENSE` file and comply with its notice requirements. This review concerns licensing, not the correctness of matching behavior.

The repository is not archived, but its last push was on 2026-05-06. That date should be considered when planning upgrades, especially because no release cadence or compatibility policy is documented. The source build also means toolchain changes can affect installation. There are no documented binaries to fall back on when a compiler setup changes.

telescope-fzf-native.nvim Compared with Telescope's fzy Option

The direct alternative named by the README is `fzy`, which is available to Telescope as a native component and as a Lua component. The difference is in the matching algorithm and query surface. This project uses a C port of the fzf algorithm and supports fzf-style exact, prefix, suffix, inverse, and OR expressions. The README presents that capability as an advantage over fzy's simpler algorithm, particularly when a query needs constraints beyond general fuzzy matching.

That does not make the choice automatic. A user who only needs basic fuzzy sorting may prefer fzy because the README identifies it as the simpler option and describes this extension as requiring a native C build. A user who values fzf query operators may prefer telescope-fzf-native.nvim despite accepting the compatibility disclaimer and missing normalization or Unicode case behavior. Neither option should be treated as a complete substitute for the standalone fzf program when full fzf coverage is required.

The practical adoption test is the expected query. If filtering by extension, prefix, or inverse substring is part of normal work, this extension has a specific reason to exist. If the workload is plain fuzzy lookup over mostly ASCII text, fzy may be the smaller conceptual fit. The decision should also account for local compiler availability because telescope-fzf-native.nvim ships no binaries.

Editorial conclusion

Neovim users who want fzf query operators inside Telescope can adopt this extension after confirming that their C toolchain builds the library and that their expected normalization and Unicode case behavior is not required. Users needing complete fzf compatibility or prebuilt libraries should first verify the documented feature gaps and build requirement.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. nvim-telescope/telescope-fzf-native.nvim on GitHub
4. README