# telescope.nvim: Fuzzy Finder and Picker Framework for Neovim

> telescope.nvim is a Lua plugin for Neovim that provides a unified fuzzy-finder interface for files, buffers, Git objects, LSP symbols, and anything else you can put in a list, built around modular pickers, sorters, and previewers.

**nvim-telescope/telescope.nvim** — Find, Filter, Preview, Pick. All lua, all the time.

- Repository: https://github.com/nvim-telescope/telescope.nvim
- Stars: 19,805 · Forks: 968
- Language: Lua
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/nvim-telescope-telescope-nvim

## What telescope.nvim Does and Who It Is For

telescope.nvim is a fuzzy finder for Neovim that collects items into a list, lets you filter them by typing, previews the selected item in a third pane, and opens the result in your editor when you confirm. The three components are a picker (which produces the list), a sorter (which ranks matches), and a previewer (which shows a preview of the selected item). All three are swappable, and many community extensions provide alternative implementations of each.

The README describes the project as a fuzzy finder over lists. This is a precise description of what it does. Any collection of items that can be enumerated can, in principle, become a telescope picker. The built-in pickers cover the most common cases: files in the project, open buffers, recent files, Git files, Git branches, Git commits, LSP document symbols, LSP workspace symbols, diagnostics, grep results across the project, and Vim help tags.

The target user is a Neovim developer who wants keyboard-driven navigation without leaving the editor. telescope.nvim replaces or supplements workflow tools like fzf run as a standalone command, Ctrl-P, or Neovim's built-in file browser.

## Architecture: Pickers, Sorters, and Previewers

The design centers on three independently replaceable concepts. A picker defines the data source: it is responsible for producing the list of items to display. Built-in pickers include find_files, live_grep, buffers, help_tags, git_branches, lsp_document_symbols, and many others. The README notes that community-driven built-in pickers, sorters, and previewers are part of the project.

A sorter ranks the items returned by the picker based on the text the user has typed. The default sorter is a pure Lua implementation. The README recommends installing a native sorter extension to improve sorting performance: either telescope-fzf-native.nvim or telescope-fzy-native.nvim. These extensions compile a C library that runs the fzf or fzy algorithm at native speed instead of going through the Lua interpreter.

A previewer renders a preview of the currently selected item. For files, the previewer shows the file content with syntax highlighting. For Git commits, it shows the diff. For LSP references, it shows the file at the referenced line. Previewers can be disabled per-picker if the preview pane is not needed or causes slowdown on large files.

## Installing telescope.nvim with lazy.nvim

telescope.nvim requires Neovim at least v0.11.7 built with LuaJIT, and the plenary.nvim plugin as a mandatory dependency. The README recommends pinning to the latest release tag to avoid breaking changes from unreleased commits. Using lazy.nvim:

```lua
{
    'nvim-telescope/telescope.nvim', version = '*',
    dependencies = {
        'nvim-lua/plenary.nvim',
        -- optional but recommended
        { 'nvim-telescope/telescope-fzf-native.nvim', build = 'make' },
    }
}
```

After installation, run `:checkhealth telescope` to verify all dependencies are found. The README calls this out as a required step. The most common missing dependencies are ripgrep for live_grep and grep_string, and fd for find_files.

For a first test, run `:Telescope find_files` at the Neovim command prompt. If it opens a picker window with your project files, the installation is working.

## Key Bindings and Basic Usage

The recommended way to expose telescope pickers is to map them to key bindings in your Neovim config. The README gives the canonical four-binding setup:

```lua
local builtin = require('telescope.builtin')
vim.keymap.set('n', '<leader>ff', builtin.find_files, { desc = 'Telescope find files' })
vim.keymap.set('n', '<leader>fg', builtin.live_grep, { desc = 'Telescope live grep' })
vim.keymap.set('n', '<leader>fb', builtin.buffers, { desc = 'Telescope buffers' })
vim.keymap.set('n', '<leader>fh', builtin.help_tags, { desc = 'Telescope help tags' })
```

Inside the picker window, the default mappings follow patterns common in insert-mode Neovim navigation. `<C-n>` and `<C-p>` move down and up the results list. `<CR>` confirms the selection and opens the file. `<C-x>` opens in a horizontal split, `<C-v>` in a vertical split, and `<C-t>` in a new tab. `<C-u>` and `<C-d>` scroll the preview window. All mappings are customizable through the setup configuration.

The `<C-/>` binding in insert mode shows all available mappings for the current picker, which is useful when learning a new picker's specific actions such as creating or deleting a Git branch from within the git_branches picker.

## Configuration and Customization

telescope.nvim is configured through a central `setup()` call that sets defaults applying to all pickers, with the option to override specific pickers by name. A minimal example with a custom key binding for showing all mappings:

```lua
require('telescope').setup{
  defaults = {
    mappings = {
      i = {
        ["<C-h>"] = "which_key"
      }
    }
  }
}
```

The `defaults` table accepts layout options, file ignore patterns, path display settings, and sorting strategy. The `pickers` table lets you configure a specific picker, for example to disable the previewer for the buffers picker or to set a custom theme. Per-picker configuration is passed as an `opts` table directly to the builtin function call when you do not want a global default.

Configuration recipes are documented on the Telescope wiki's Configuration-Recipes page. Themes shipped with telescope.nvim include dropdown, cursor, and ivy styles that change the picker's window shape. The setup documentation lives at `:help telescope.setup()` and `:help telescope.builtin` inside Neovim.

## Dependencies, Performance, and When to Use fzf-native

The soft dependencies ripgrep and fd are not strictly required to install telescope.nvim, but they are required for two of its most-used pickers. `live_grep` and `grep_string` require ripgrep. `find_files` uses ripgrep first and falls back to fd if ripgrep is absent. If neither is installed, find_files falls back to the system `find` command, which is slower on large codebases.

The native sorter extension is marked as optional but strongly recommended by the README for sorting performance. The fzf-native extension compiles a C library (via `make` as the build step in the lazy.nvim config) that runs the fzf algorithm. Without this extension, sorting runs in pure Lua, which is noticeably slower on large file lists. If fzf-native fails to compile, the pure Lua sorter still works; sorting is just slower.

devicons (nvim-web-devicons) adds file type icons to picker results. This is a cosmetic dependency; telescope.nvim works without it.

A Luarocks package is available for telescope.nvim, as shown by the badge in the README. The Makefile provides a `docgen` target that generates documentation using a separate docgen.nvim tool.

## The Extension Ecosystem and telescope.nvim vs fzf-lua

telescope.nvim has a large community extension ecosystem documented on the Extensions wiki page. Extensions add pickers for specific sources: package managers, project directories, GitHub issues, file browsers, clipboard managers, and more. Extensions are loaded through `require('telescope').load_extension('name')` after installation.

fzf-lua is the primary alternative in the Neovim fuzzy-finder space. It is also written in Lua and also provides file, buffer, grep, and LSP pickers. fzf-lua uses fzf as its core algorithm from the start rather than as an optional extension, which generally means faster sorting out of the box. fzf-lua is a single self-contained plugin with fewer moving parts; telescope.nvim is a framework where the core is deliberately separate from the algorithm.

The choice between them often comes down to configuration philosophy. telescope.nvim's modular design means you can swap sorters, previewers, and pickers independently. fzf-lua is less modular but requires fewer decisions to reach a fast default configuration. Both projects are actively maintained; telescope.nvim's last push was on 2026-08-17.

## Conclusion

telescope.nvim suits Neovim users who want a single, extensible picker interface for files, symbols, and grep results, and who are willing to pin a stable version tag and add the fzf-native extension to get acceptable sorting performance. It is the wrong fit if you run an older Neovim release, since the README requires Neovim at least v0.11.7 built with LuaJIT, and older versions will not be supported. Run `:checkhealth telescope` after installation to catch missing dependencies before relying on live_grep or find_files in daily use. The extension ecosystem on the wiki is large, but extensions are community-maintained and vary in quality.

## FAQ

### How do you open telescope in Neovim?

Run `:Telescope find_files` at the Neovim command prompt to open the file picker, or map the picker to a key binding using `vim.keymap.set('n', '<leader>ff', require('telescope.builtin').find_files)`.

### What does telescope.nvim do in Neovim?

telescope.nvim provides a fuzzy-finder interface over lists. It lets you search for files, buffers, grep results, Git objects, LSP symbols, and Vim help tags, preview the selected item, and open it in the editor.

### How do you install telescope.nvim?

Add it to your plugin manager with plenary.nvim as a required dependency. Using lazy.nvim, set `version = '*'` to pin to the latest stable tag. After installation, run `:checkhealth telescope` to verify all dependencies.

### How does telescope.nvim compare to fzf-lua?

telescope.nvim is a modular framework where pickers, sorters, and previewers are independently replaceable; fzf-lua uses fzf as its core algorithm by default for faster out-of-the-box sorting with a simpler setup. Both support files, buffers, grep, and LSP pickers.

## Sources

- [Issues](https://github.com/nvim-telescope/telescope.nvim/issues)
- [License: MIT](https://github.com/nvim-telescope/telescope.nvim/blob/master/LICENSE)
- [nvim-telescope/telescope.nvim on GitHub](https://github.com/nvim-telescope/telescope.nvim)
- [README](https://github.com/nvim-telescope/telescope.nvim/blob/master/README.md)
- [Releases](https://github.com/nvim-telescope/telescope.nvim/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nvim-telescope-telescope-nvim