nvim-telescope /telescope.nvim
Find, Filter, Preview, Pick. All lua, all the time.
★ 19,861⑂ 967👁 48⑃ 1,620● 2,005▤ 12
+2
Daily
+13
Weekly
+42
Monthly
19,861
stars
967
forks
48
watchers
1,620
prs
2,005
issues
12
releases
README
telescope.nvim
Gaze deeply into unknown regions using the power of the moon.
What Is Telescope?
telescope.nvim is a highly extendable fuzzy finder over lists. Built on the
latest awesome features from neovim core. Telescope is centered around
modularity, allowing for easy customization.
Community driven builtin pickers, sorters and
previewers.
!Preview
For more showcases of Telescope, please visit the Showcase
section in the
Telescope Wiki
Telescope Table of Contents
- Getting Started
- Usage
- Customization
- Default Mappings
- Pickers
- Previewers
- Sorters
- Layout
- Themes
- Commands
- Autocmds
- Extensions
- API
- Media
- Contributing
- Changelog
Getting Started
This section should guide you to run your first builtin pickers.
Requirements
Neovim =v0.11.7 built with LuaJIT (check :version).
nvim-lua/plenary.nvim.
[!IMPORTANT]
Only the latest version (stable) and the latest commit of HEAD (nightly) are tested and supported; before opening an issue, download the latest available release and confirm that the problem persists.
Recommended dependencies
BurntSushi/ripgrep is required for
live_grep and grep_string and is the first priority for find_files.
sharkdp/fd (finder)
devicons (icons)
We also strongly suggest installing a native telescope sorter to significantly improve
sorting performance:
telescope-fzf-native.nvim
or
telescope-fzy-native.nvim.
For more information and a performance benchmark take a look at the
Extensions
wiki.
Installation
We recommend pinning to the latest release
tag,
e.g. 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' },
}
}
Checkhealth
Make sure you call :checkhealth telescope after installing telescope to ensure
everything is set up correctly.
After this setup you can continue reading here or switch to :help telescope
to get an understanding of how to use Telescope and how to configure it.
Usage
Try the command :Telescope find_files
to see if telescope.nvim is installed correctly.
lua
local builtin = require('telescope.builtin')
vim.keymap.set('n', 'ff', builtin.find_files, { desc = 'Telescope find files' })
vim.keymap.set('n', 'fg', builtin.live_grep, { desc = 'Telescope live grep' })
vim.keymap.set('n', 'fb', builtin.buffers, { desc = 'Telescope buffers' })
vim.keymap.set('n', 'fh', builtin.help_tags, { desc = 'Telescope help tags' })
See builtin pickers for a list of all builtin functions.
Customization
This section should help you explore available options to configure and
customize your telescope.nvim.
Unlike most vim plugins, telescope.nvim can be customized by either applying
customizations globally, or individually per picker.
- Global Customization affecting all pickers can be done through the main
setup() method (see defaults below)
- Individual Customization affecting aTop issues
#1048Open multiple files at once57 comments · 2021-07-25#2201find_files and grep in selected directory39 comments · 2022-10-19#559Opening files leads to problems with restoring views and treesitter36 comments · 2021-02-26#2446Unable to preview and open files with parentheses in the path25 comments · 2023-03-28#1174attempt to yield across metamethod/C-call boundary24 comments · 2021-08-27#2552Remove plenary dependency23 comments · 2023-06-07#647Out of memory error in previewer20 comments · 2021-03-12#1766Combining grep_string and live_grep to a third option19 comments · 2022-03-01
Discussions
#3684How do I create a custom telescope picker able to take the search-path in the prompt itself?1 comments · 2026-06-28#3680How to set a theme on a picker AND some other options.1 comments · 2026-06-15#3678ccline: fuzzy-find commands with AI when you leave Neovim for the shell1 comments · 2026-06-10#3674Is there support for mini.icons instead of devicons1 comments · 2026-05-29#3671Can I add hidden keywords to the keymaps picker?1 comments · 2026-05-27#3665Show hidden files in find_files only when search string begins with "."0 comments · 2026-05-13#3652How to use Telescope with vim.pack instead of Lazy?4 comments · 2026-04-20#3643Decouple the builtin find_files finder from the picker3 comments · 2026-04-08
Latest release
v0.2.1 v0.2.1 2025-12-31What's Changed ci: bump actions/cache from 4 to 5 by @dependabot[bot] in https://github.com/nvim-telescope/telescope.nvim/pull/3591 fix(pickers): remove broken highlight call for autocmds by @clason in https://github.com/nvim-telescope/telescope.nvim/pull/3594 fix(actions): fixes 699 by @alexmozaidze in https://github.com/nvim-telescope/telescope.nvim/pull/3595 feat(builtin.colorscheme): update option ignore_builtins by @auipga in https://github.com/nvim-telescope/telescope.nvim/pull/3511 fix(reuse_win): handle reuse_win for current file jump by @UN-9BOT in https://github.com/nvim-t