nvim-lspconfig is a collection of LSP server configurations for the Nvim LSP client.
View all configs, or run :help lspconfig-all from Nvim.
require('lspconfig')(the legacy "framework" of nvim-lspconfig) is deprecated in favor of vim.lsp.config (Nvim 0.11+).- The lspconfig.lua module will be dropped. Calls to
require('lspconfig')will show a warning, which will later become an error.
- The lspconfig.lua module will be dropped. Calls to
- nvim-lspconfig itself is NOT deprecated. It provides server-specific configs.
- The configs live in the lsp/ directory.
vim.lsp.configautomatically finds them and merges them with any locallsp/*.luaconfigs defined by you or a plugin. - The old configs in lua/lspconfig/ are deprecated and will be removed.
- The configs live in the lsp/ directory.
- Upgrade to Nvim 0.11+
- (Optional) Use
vim.lsp.config('…')(notrequire'lspconfig'.….setup{}) to customize or define a config. - Use
vim.lsp.enable('…')(notrequire'lspconfig'.….setup{}) to enable a config, so that it activates for itsfiletypes.
These configs are best-effort and supported by the community (you). See contributions.
- Ask questions on GitHub Discussions, not the issue tracker.
- If you found a bug in Nvim LSP (
:help lsp), report it to Neovim core.- Do not report it here. Only configuration data lives here.
- Requires Nvim 0.11.3+.
- Support for Nvim 0.10 will be removed. Upgrade Nvim and nvim-lspconfig before reporting an issue.
- With Nvim 0.12+, you can use the builtin
vim.packplugin manager:vim.pack.add{ { src = 'https://github.com/neovim/nvim-lspconfig' }, }
- Or install nvim-lspconfig using Vim's "packages" feature:
git clone https://github.com/neovim/nvim-lspconfig ~/.config/nvim/pack/nvim/start/nvim-lspconfig - Or use a 3rd-party plugin manager.
- Install a language server, e.g. pyright
npm i -g pyright
- Enable its config in your init.lua (:help lsp-quickstart).
vim.lsp.enable('pyright')
- Ensure your project/workspace contains a root marker as specified in
:help lspconfig-all. - Open a code file in Nvim. LSP will attach and provide diagnostics.
nvim main.py - Run
:checkhealth vim.lspto see the status or to troubleshoot.
See :help lspconfig-all for the full list of server-specific details. For
servers not on your $PATH (e.g., jdtls, elixirls), you must manually set
the cmd parameter:
vim.lsp.config('jdtls', {
cmd = { '/path/to/jdtls' },
}):LspInfo(alias to:checkhealth vim.lsp) shows the status of active and configured language servers.:lsp enable [<config_name>](:LspStartfor Nvim 0.11 or older) Start the requested server name. Will only successfully start if the command detects a root directory matching the current config.:lsp disable [<config_name>](:LspStopfor Nvim 0.11 or older) Stops the given server. Defaults to stopping all servers active on the current buffer. To force stop use:LspStop!:lsp restart [<client_name>](:LspRestartfor Nvim 0.11 or older) Restarts the given client, and attempts to reattach to all previously attached buffers. Defaults to restarting all active servers.
Nvim sets default options and mappings when LSP is active in a buffer:
To customize, see:
Extra settings can be specified for each LSP server. With Nvim 0.11+ you can
extend a config by calling
vim.lsp.config('…', {…}).
vim.lsp.config('rust_analyzer', {
-- Server-specific settings. See `:help lsp-quickstart`
settings = {
['rust-analyzer'] = {},
},
})Configs are sourced in this order:
lsp/in 'runtimepath'after/lsp/in 'runtimepath'vim.lsp.config()
If you install nvim-lspconfig or similar plugins, the order that configs are applied depends on the load order. To ensure that your own config "wins" and overrides the others, use after/lsp/ and/or vim.lsp.config() to override/extend the defaults.
- Run
:lua vim.lsp.config('foo', {cmd={'true'}}) - Run
:lua vim.lsp.enable('foo') - Run
:checkhealth vim.lsp, the new config is listed under "Enabled Configurations". 😎
- Create a file
after/lsp/foo.luasomewhere on your 'runtimepath'.:exe 'edit' stdpath('config') .. '/after/lsp/foo.lua' - Add this code to the file (or copy any of the examples from the lsp/ directory in this repo):
return { cmd = { 'true' }, } - Save the file (with
++pto ensure its parent directory is created).:write ++p - Enable the config.
:lua vim.lsp.enable('foo') - Run
:checkhealth vim.lsp, the new config is listed under "Enabled Configurations". 🌈
nvim-lspconfig generates Lua type definitions for each supported LSP server.
By manually adding annotations (e.g., ---@type lspconfig.settings.server_name),
you enable auto-completion and diagnostics for your server settings.
Example:
---@type vim.lsp.Config
local config = {
---@type lspconfig.settings.lua_ls
settings = {
Lua = {
runtime = {
version = 'LuaJIT',
},
workspace = {
preloadFileSize = 10000,
library = {
vim.env.VIMRUNTIME,
}
},
},
},
}
vim.lsp.config('lua_ls', config)Start with :checkhealth vim.lsp to troubleshoot. The most common reasons a language server does not start or attach are:
-
Language server is not installed. nvim-lspconfig does not install language servers for you. You should be able to run the
cmddefined in the config from the command line and see that the language server starts. If thecmdis a name instead of an absolute path, ensure it is on your$PATH. -
Missing filetype plugins. Some languages are not detected by Nvim because they have not yet been added to the filetype detection system. Ensure
:set filetype?shows the filetype and not an empty value. -
Not triggering root detection. Some language servers require a "workspace", which is found by looking for an ancestor directory that contains a "root marker". The most common root marker is
.git/, but each config defines other "root marker" names. Root markers/directories are listed in:help lspconfig-all.You can also explicitly set a root instead of relying on automatic detection by enabling
'exrc'and adding an.nvim.luaat the desired root dir with the following code:vim.lsp.config('<client name>', { root_dir = vim.fn.fnamemodify(debug.getinfo(1, 'S').source:sub(2), ':p:h'), })
Note that prior to nvim 0.12
exrcfile is executed only if it's inside of a cwd where you startnvim.
If you found a bug with LSP functionality, report it to Neovim core.
Before reporting a bug, check your logs and the output of :checkhealth vim.lsp. Add this to your init.lua to enable verbose logging:
vim.lsp.log.set_level('debug')Attempt to run the language server, then run :LspLog to open the log.
Most of the time, the reason for failure is present in the logs.
If a language server is missing from configs.md, contributing a new configuration for it helps others, especially if the server requires special setup. Follow these steps:
- Read CONTRIBUTING.md.
- Create a new file at
lsp/<server_name>.lua.- Copy an existing config to get started. Most configs are simple. For an extensive example see texlab.lua.
- Ask questions on GitHub Discussions or in the Neovim Matrix room.
To publish a release:
- Create and push a new tag.
- After pushing the tag, a GitHub action will automatically package the plugin and publish the release to LuaRocks.
Copyright Neovim contributors. All rights reserved.
nvim-lspconfig is licensed under the terms of the Apache 2.0 license.
See LICENSE.md