telescope.nvim — Fuzzy Finder and Picker Framework for Neovim

Introduction

telescope.nvim is a fuzzy finder framework for Neovim written in Lua. It provides built-in pickers for files, grep, buffers, LSP symbols, and Git objects, and exposes an API for creating custom pickers that integrate with any data source.

What telescope.nvim Does

• Searches files, directories, and buffer contents with fuzzy matching
• Runs live grep across a project using ripgrep as a backend
• Browses LSP references, definitions, symbols, and diagnostics
• Navigates Git commits, branches, stashes, and changed files
• Supports previewing files, images, and custom content in a floating window

Architecture Overview

telescope.nvim consists of three components: pickers (what to search), sorters (how to rank results), and previewers (how to display selections). Each picker spawns an asynchronous job (often ripgrep or fd) and streams results into a floating window. A sorter like fzf-native scores results in real time. Extensions can register new pickers that plug into the same UI and keymap infrastructure.

Self-Hosting & Configuration

• Install via any Neovim plugin manager with plenary.nvim as a dependency
• Optionally install telescope-fzf-native for faster sorting
• Configure default pickers, themes, and mappings in the setup() call
• Bind keys to built-in pickers like find_files, live_grep, buffers
• Requires ripgrep and fd for optimal file search performance

Key Features

• Extensible picker API for building custom search interfaces
• Real-time preview with syntax highlighting for matched files
• Themes (dropdown, cursor, ivy) change layout without custom code
• telescope-fzf-native extension provides compiled C sorter for speed
• 100+ community extensions covering everything from Docker to DAP

Comparison with Similar Tools

• fzf.vim — wraps the fzf binary; telescope is Lua-native with richer preview and extension support
• ctrlp.vim — legacy Vimscript fuzzy finder; telescope is faster and more extensible
• mini.pick — minimal single-file picker; telescope has a larger ecosystem of pickers and extensions
• fzf-lua — fzf integration for Neovim; telescope uses its own sorter pipeline and API
• Snacks.picker — newer picker framework; telescope has a more mature extension ecosystem

FAQ

Q: Why is telescope slow on large projects? A: Install telescope-fzf-native for compiled sorting, and ensure ripgrep and fd are on your PATH.

Q: Can I use telescope without a Nerd Font? A: Yes. Disable icons in the configuration or use a text-only theme.

Q: How do I create a custom picker? A: Use the pickers.new() API with a custom finder, sorter, and optional previewer.

Q: Does telescope work with Neovim 0.9? A: Yes. telescope.nvim supports Neovim 0.9 and later.

Sources

• https://github.com/nvim-telescope/telescope.nvim
• https://github.com/nvim-telescope/telescope.nvim/blob/master/doc/telescope.txt