nvim-cmp: a Lua completion engine for Neovim that ships with no completion sources of its own

The engine does not complete anything until you add sources

nvim-cmp calls itself a completion engine plugin for Neovim written in Lua, and the word engine is precise. Completion sources are installed from external repositories and "sourced" into it. Without at least one source plugin, nvim-cmp has nothing to suggest. Suggestions from a language server come through cmp-nvim-lsp, words from open buffers through cmp-buffer, file system paths through cmp-path, and command line completion through cmp-cmdline. Each is its own repository under hrsh7th.

This split is what answers the question of what nvim-cmp does: it collects candidates from whatever sources you register, shows them in a menu and handles the key mappings that accept or move through them. The project lists its aims as full support for LSP completion related capabilities, customizability through Lua functions, smart handling of key mappings, and no flicker. The cost is plugin count. The recommended LSP setup means tracking the engine plus four or five source plugins, each with its own update history, and finding more sources means browsing the project wiki's List of sources page or the nvim-cmp GitHub topic.

The recommended setup is written for vim-plug and vim-vsnip

The one configuration on the project's front page uses vim-plug as the plugin manager and vim-vsnip for snippets. It installs nvim-lspconfig alongside the engine and the four core sources:

call plug#begin(s:plug_dir)
Plug 'neovim/nvim-lspconfig'
Plug 'hrsh7th/cmp-nvim-lsp'
Plug 'hrsh7th/cmp-buffer'
Plug 'hrsh7th/cmp-path'
Plug 'hrsh7th/cmp-cmdline'
Plug 'hrsh7th/nvim-cmp'

" For vsnip users.
Plug 'hrsh7th/cmp-vsnip'
Plug 'hrsh7th/vim-vsnip'

That example is Vimscript for vim-plug. Anyone on a different plugin manager, such as lazy.nvim, has to translate the plugin list and the setup call themselves, because the README shows no other manager. Advanced configuration examples live on the GitHub wiki rather than in the repository. The practical effect is that the most searched setup paths, lazy loading and distribution specific configs among them, depend on wiki pages and third party write ups, which can drift out of date when the engine changes.

Snippets require a second plugin and a matching adapter

nvim-cmp does not expand snippets itself. The recommended configuration pairs each snippet engine with a cmp adapter plugin, and the commented lines show the supported pairs. vsnip users install hrsh7th/vim-vsnip with hrsh7th/cmp-vsnip. LuaSnip users install L3MON4D3/LuaSnip with saadparwaiz1/cmp_luasnip. mini.snippets users install echasnovski/mini.snippets with abeldekat/cmp-mini-snippets. UltiSnips users install SirVer/ultisnips with quangnguyen30192/cmp-nvim-ultisnips. Snippy users install dcampos/nvim-snippy with its own adapter.

The consequence is that choosing a snippet engine adds two plugins, not one, and the adapters come from several different authors. If an adapter falls behind a change in nvim-cmp or in its snippet engine, completion of snippet items breaks even though both main plugins are current. When debugging, check the adapter repository as well as the engine.

cmp.mapping.preset can change without announcement

The README's opening notes include a warning that is easy to skip. cmp.mapping.preset.* is a pre-defined configuration that aims to mimic Neovim's native like behavior, and it can be changed without announcement. The author's instruction is plain: manage key mappings yourself.

Many example configurations build their mappings on top of a preset because it saves writing every key. Under this policy, an update to nvim-cmp can change what Tab, Enter or the arrow keys do in insert mode, with no entry in a changelog and no version bump to warn you. The consequence lands at the worst moment, in the middle of editing. The defensive approach is to write out each mapping you rely on explicitly in Lua, so that a preset change upstream has nothing to override in your config.

Breaking changes are tracked in issue 231, not in releases

The repository has two tagged releases: v0.0.1 from August 14, 2022, and v0.0.2 from January 7, 2025. Development happens on the main branch, with the last push on July 9, 2026. Version tags therefore say little about what changed, and a plugin manager that follows tags would sit on a 2025 snapshot.

Instead, breaking changes go into a single GitHub issue, number 231, and the README asks users to subscribe to it to be notified of upcoming breaking changes. That works if you subscribe and read the notifications. If you track main through a plugin manager without pinning, an update can bring a breaking change you never saw announced in your editor. Pin a commit, update deliberately, and check issue 231 before moving the pin forward.

A hobby project that will not chase reports without a minimal config

The author states that nvim-cmp is a hobby project, supported through GitHub Sponsors. Bug reports are welcome, but the README says not to expect a fix unless the report includes a minimal configuration and steps to reproduce.

Given how many plugins a working setup involves, this rule matters. A bug that appears in a full Neovim config with a dozen plugins may come from a source plugin, a snippet adapter, a preset mapping or a distribution's defaults. Before filing, reduce the config to nvim-cmp and the one source that misbehaves. If you cannot reproduce it there, the problem sits in another repository. Teams that depend on fast turnaround for editor bugs should factor in that one maintainer sets the pace and no service level is offered.

Lua throughout, checked with luacheck and tested with vusted

The code lives under lua/, with plugin/ and autoload/ directories for Neovim's loading conventions and a doc/ directory alongside. A rockspec, nvim-cmp-scm-1.rockspec, packages it for LuaRocks style tooling, stylua.toml sets formatting, and .luacheckrc configures the linter. The Makefile defines the checks contributors run:

luacheck ./lua
vusted --output=gtest ./lua

The pre-commit and integration targets run luacheck lua followed by vusted lua. Contributors need luacheck and vusted installed locally to run these targets. For users the layout has one practical meaning: the engine is pure Lua, so configuration happens in Lua functions, and the README's "Concept" list names customization through those functions as a core aim. There is no comparison in the repository against blink.cmp, coc.nvim, mini.completion or Neovim's built in completion, so any choice between them has to be made on your own testing.

Editorial conclusion

nvim-cmp suits Neovim users who are willing to assemble completion from parts: the engine, one plugin per source, a snippet engine with its adapter, and key mappings they write themselves. It does not suit someone who wants completion that works after installing a single plugin, or who expects tagged releases to signal breaking changes. Before adopting it, subscribe to issue 231, pin a commit in your plugin manager, and copy the mappings you want into your own config instead of leaning on cmp.mapping.preset.

Frequently asked questions

Official sources

1. hrsh7th/nvim-cmp on GitHub
2. Issues
3. License: MIT
4. README
5. Releases