nvim-lspconfig after the require('lspconfig') deprecation: server configs for Nvim 0.11+

The problem nvim-lspconfig solves now is narrower than it used to be

Neovim's built-in LSP client knows how to talk to a language server. It does not know that pyright is launched as pyright-langserver, which filetypes it should attach to, or which files in a project mark the root. Every user would otherwise rediscover those details per server.

nvim-lspconfig is a collection of those per-server details. The README describes it as "a collection of LSP server configurations for the Nvim LSP client", and stresses that only configuration data lives in the repository: bugs in the LSP client itself belong in Neovim core, not here.

The audience has shifted with it. Previously you installed nvim-lspconfig to get a Lua framework that started servers. Now the framework half is gone and what remains is a set of files under lsp/ that Nvim reads on its own. If you are on Nvim 0.11.3+, you are mostly consuming data, not calling an API.

How vim.lsp.config finds the lsp/ directory and merges your overrides

The mechanism is file discovery. The configs live in the lsp/ directory of the repository, and the README states that vim.lsp.config automatically finds them and merges them with any local lsp/*.lua configs defined by you or a plugin. There is no registration call and no setup function to invoke before the server can be enabled.

Merging is ordered, and the order is documented. Configs are sourced from lsp/ in 'runtimepath', then after/lsp/ in 'runtimepath', then vim.lsp.config(). Because a plugin installed through a package manager sits somewhere in 'runtimepath', the README warns that the order in which configs are applied depends on load order, and that the way to make your own config win is to place it in after/lsp/ or pass it through vim.lsp.config().

The old code path still exists but is on the way out. The README marks require('lspconfig') as deprecated in favor of vim.lsp.config, says the lspconfig.lua module will be dropped, and notes that calls to require('lspconfig') will show a warning which will later become an error. The configs under lua/lspconfig/ are described as deprecated and slated for removal. The repository itself is not deprecated; only that entry point is.

Installing nvim-lspconfig and enabling pyright in a first session

Installation requires Nvim 0.11.3 or newer per the README. On Nvim 0.12+, the builtin vim.pack manager can fetch it:

vim.pack.add{
  { src = 'https://github.com/neovim/nvim-lspconfig' },
}

Without a plugin manager, the README gives the packages route, which clones into a start directory so the plugin loads automatically:

git clone https://github.com/neovim/nvim-lspconfig ~/.config/nvim/pack/nvim/start/nvim-lspconfig

A third-party plugin manager is also listed as an option. Note what is not included: nvim-lspconfig does not install language servers. You install the server yourself. For pyright the README shows:

npm i -g pyright

Then enable the config in init.lua. This is the line that replaces the old setup call:

vim.lsp.enable('pyright')

Open a file in a project that contains the root marker listed in :help lspconfig-all, for example nvim main.py, and the server attaches. Run :checkhealth vim.lsp to see status. If the server is not on your $PATH, as with jdtls or elixirls, the README says you must set cmd manually:

vim.lsp.config('jdtls', {
  cmd = { '/path/to/jdtls' },
})

Server-specific settings go through the same call. The README's rust_analyzer example passes an empty table under settings, keyed by the server's own name:

vim.lsp.config('rust_analyzer', {
  settings = {
    ['rust-analyzer'] = {},
  },
})

Config priority is the part people get wrong

The documented order is lsp/, then after/lsp/, then vim.lsp.config(). Two consequences follow, and both bite in practice.

First, a config shipped by a distribution or another plugin can override yours if it lands later in the load order. The README's answer is explicit: to ensure your own config wins, use after/lsp/ and/or vim.lsp.config(). If you edit a config inside the plugin directory itself, an update wipes it and you have also changed nothing about priority.

Second, the merge is not a replacement. vim.lsp.config() extends a config rather than discarding it, which is why the rust_analyzer example only supplies settings and lets the shipped config provide cmd and filetypes. If you wanted to remove a default you would have to know which layer set it. The README does not document an unset or delete mechanism, so a default you disagree with is something you override rather than remove.

The type annotations exist to make this less error-prone. nvim-lspconfig generates Lua type definitions for each supported server, and the README shows annotating a local table with ---@type lspconfig.settings.lua_ls so that settings keys autocomplete and get checked. That only helps if your editor setup runs a Lua language server over your config, which is a separate install.

Where nvim-lspconfig is the wrong tool

The README's support section is blunt: these configs are "best-effort and supported by the community (you)", questions belong on GitHub Discussions rather than the issue tracker, and LSP client bugs go to Neovim core. That is a real constraint on expectations. A server flag that changed upstream may sit unfixed until someone contributes the patch, and the project will not treat it as a defect in the client.

The second failure mode is version drift. Support for Nvim 0.10 will be removed, and the README tells you to upgrade Neovim and nvim-lspconfig before reporting an issue. If your environment is pinned to an older Neovim, this plugin is moving away from you.

The third is the deprecation itself. Any configuration still calling require('lspconfig') is on a path the README says will produce a warning and later an error. That is not a bug you can wait out.

Troubleshooting is narrow by design. The README lists the most common causes of a server failing to start or attach: the server is not installed, or the cmd is a bare name that is not on $PATH. Both are outside the plugin. If :checkhealth vim.lsp shows the config enabled but no client attached, the README points at the root marker, not at nvim-lspconfig.

nvim-lspconfig versus Mason, and versus writing configs yourself

The comparison people search for is nvim-lspconfig against mason. They solve different halves of the problem. nvim-lspconfig supplies configuration data: cmd, filetypes and root markers for a server. It does not install servers, and the README says so directly. Mason is a package manager for editor tooling, so it handles the install half. Nothing in the README describes an integration between the two, and the repository has no dependency on Mason; the pairing is something users assemble. If your problem is "the server binary is not on this machine", nvim-lspconfig is not the answer.

The other comparison is against doing it yourself. You can write after/lsp/foo.lua with a cmd table and skip the plugin entirely, which the README's own "Creating a config" section demonstrates. That is a legitimate choice for one or two servers you know well. The plugin earns its place when you want the accumulated per-server details, the generated type annotations, and a config that already handles the filetypes and root markers you would otherwise look up. The trade is that you inherit someone else's defaults and the priority rules that come with them.

On the commands side, the surface is small: :LspInfo as an alias to :checkhealth vim.lsp, :lsp enable, :lsp disable and :lsp restart, with :LspStart, :LspStop and :LspRestart named as the equivalents on Nvim 0.11 or older. Note that :lsp enable only succeeds if the command detects a root directory matching the current config, which is the same root-marker requirement that trips people up on attach.

Licence, upgrade cost and what the repository expects from contributors

The project is Apache-2.0, and the repository carries a LICENSE.md. That is a permissive licence with an explicit patent grant, which matters if you vendor the lsp/ files into a product. This is not legal advice; check the terms yourself if you redistribute.

The upgrade cost is concentrated in one migration. The README's steps are: upgrade to Nvim 0.11+, optionally use vim.lsp.config('…') to customize or define a config, and use vim.lsp.enable('…') in place of require'lspconfig'.….setup{}. The mechanical work is replacing setup calls with enable calls and moving any overrides into after/lsp/ or vim.lsp.config(). The risk is silent: if a config you previously set up by hand is now provided by the plugin, the plugin's version applies unless your layer wins.

Contribution expectations are visible in the repository layout. There is a Makefile with test and lint targets, running vusted ./test, stylua --check . and emmylua_check ., so a patch to a config is expected to pass formatting and type checks before it lands. There is also a rockspec, nvim-lspconfig-scm-1.rockspec, so LuaRocks is a supported distribution channel alongside the git clone and vim.pack routes. The last push to the default branch was on 2026-09-18, and the most recent release listed is v2.11.0 on 2026-07-21.

Editorial conclusion

Adopt nvim-lspconfig if you run Nvim 0.11.3 or newer and want server-specific defaults without writing them yourself; skip it if you are still on 0.10, since the README states support for 0.10 will be removed. Before migrating, check that the server binary starts from your shell, then run :checkhealth vim.lsp and confirm your server appears under Enabled Configurations rather than only under active clients.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. neovim/nvim-lspconfig on GitHub
4. README
5. Releases