Guide · Open source

How to use telescope.nvim: install, search files and tips

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

telescope.nvim is a fuzzy finder plugin for Neovim, the text editor. It lets you search and pick from lists such as files, open buffers, help tags and search results, with a preview of the highlighted item. This guide shows you how to install it, run your first pickers, map keys to them and start customizing.

Telescopenvim-telescope/telescope.nvim · ★ 19.8k · MIT Install options & downloads

Quick start

1Check your Neovim version. Confirm Neovim 0.11.7 or newer built with LuaJIT by running :version.
2Add the plugin spec. Add telescope.nvim with plenary.nvim and optionally telescope-fzf-native.nvim to your lazy.nvim plugin spec.
3Install ripgrep. Install ripgrep, which live_grep and grep_string require.
4Run checkhealth. Run :checkhealth telescope to confirm the setup.
5Try find_files. Run :Telescope find_files and type a few characters to narrow the list.
6Add key mappings. Map keys such as <leader>ff to builtin.find_files and <leader>fg to builtin.live_grep.

What do you need before installing telescope.nvim?

telescope.nvim is a Neovim plugin, so it does not run as a standalone app. The README asks for Neovim 0.11.7 or newer built with LuaJIT (you can check this with :version) and the plenary.nvim plugin.

Only the latest stable release and the latest commit of HEAD are tested and supported. Before opening an issue, download the latest available release and confirm the problem still happens.

Neovim 0.11.7 or newer, built with LuaJIT
plenary.nvim
ripgrep, required for live_grep and grep_string and the first priority for find_files
Optional: fd for finding files, devicons for icons, and telescope-fzf-native.nvim for faster sorting

How do you install telescope.nvim with lazy.nvim?

The README recommends pinning to the latest release tag and shows lazy.nvim as an example. Add this table to your plugin spec. The fzf-native entry is optional but recommended and is built with make.

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

How do you check that the install works?

Run :checkhealth telescope after installing to confirm everything is set up correctly. Then try :Telescope find_files to see whether telescope.nvim is working.

:checkhealth telescope

How do you map keys to Telescope pickers?

Pickers are the builtin lists such as files, buffers and help tags. The README shows Lua key mappings for four common ones. Put them in your Neovim config so you can open a picker with a key instead of typing the command.

<leader>ff opens find_files
<leader>fg opens live_grep
<leader>fb opens buffers
<leader>fh opens help_tags

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' })

How do you move around and pick items?

Type a few characters to narrow the list. Use the default mappings to move through results and confirm. The README lists the common keys below. Press ? in normal mode, or <C-/> in insert mode, to see the actions for the current picker.

<C-n> or <Down>: next item; <C-p> or <Up>: previous item
<CR>: confirm selection
<C-x> opens the file in a split, <C-v> in a vsplit, <C-t> in a new tab
<Tab> toggles selection and moves to the next item
<C-q> sends all unfiltered items to the quickfix list
<Esc> closes Telescope in normal mode, <C-c> in insert mode

How do you customize Telescope?

You can customize Telescope globally through the setup() method, or for one picker by passing opts to a builtin picker. The README shows the structure with defaults, pickers and extensions sections. For every default option, read :help telescope.setup(). For picker options, read :help telescope.builtin.

For example, this maps <C-h> in insert mode to the which_key action. The README notes the default is <C-/>.

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

What people use it for

Opening a file in a large codebase by typing part of its name with find_files
Searching text across a project with live_grep, which needs ripgrep
Switching between open buffers with the buffers picker
Looking up Neovim help topics with the help_tags picker
Customizing one picker's behaviour without changing the others

Frequently asked questions

Is telescope.nvim free?

Yes. telescope.nvim is released under the MIT licence, according to the project's listing. Check the repository's licence file for the full terms.

What do I need to install telescope.nvim?

You need Neovim 0.11.7 or newer built with LuaJIT and the plenary.nvim plugin. ripgrep is required for live_grep and grep_string.

Does telescope.nvim work outside Neovim?

No. It is a plugin for Neovim and does not run as a standalone application.

How do I install telescope.nvim with lazy.nvim?

Add the plugin spec with version set to '*', plenary.nvim as a dependency, and optionally telescope-fzf-native.nvim built with make. The README gives the full table.

Why does live_grep not work?

live_grep and grep_string need ripgrep installed. Run :checkhealth telescope to check the setup, and confirm your Neovim version is supported.

What are the alternatives to telescope.nvim?

The project lists fzf-lua, snacks.nvim, fzf.vim and ctrlp.vim as comparable projects. Try the one whose defaults and configuration fit your workflow.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

telescope.nvim suits Neovim users who want fast fuzzy search for files and text and are comfortable configuring it in Lua. If you do not use Neovim, want a point-and-click app, or run an unsupported older Neovim, pick something else such as one of the comparable projects listed.

Install options & downloads