nvim-lspconfig README

The project's README from github.com/neovim/nvim-lspconfig. As one markdown file: README.md.

nvim-lspconfig

nvim-lspconfig is a collection of LSP server configurations for the Nvim LSP client.

View all configs, or run :help lspconfig-all from Nvim.

Important ⚠️

Migration instructions

  1. Upgrade to Nvim 0.11+
  2. (Optional) Use vim.lsp.config('…') (not require'lspconfig'.….setup{}) to customize or define a config.
  3. Use vim.lsp.enable('…') (not require'lspconfig'.….setup{}) to enable a config, so that it activates for its filetypes.

Support

These configs are best-effort and supported by the community (you). See contributions.

Install

LuaRocks

Quickstart

  1. Install a language server, e.g. pyright
    npm i -g pyright
  2. Enable its config in your init.lua (:help lsp-quickstart).
    vim.lsp.enable('pyright')
  3. Ensure your project/workspace contains a root marker as specified in :help lspconfig-all.
  4. Open a code file in Nvim. LSP will attach and provide diagnostics.
    nvim main.py
  5. Run :checkhealth vim.lsp to 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' },
})

Commands

Configuration

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'] = {},
  },
})

Config priority

Configs are sourced in this order:

  1. lsp/ in 'runtimepath'
  2. after/lsp/ in 'runtimepath'
  3. 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.

Creating a config

As code

  1. Run :lua vim.lsp.config('foo', {cmd={'true'}})
  2. Run :lua vim.lsp.enable('foo')
  3. Run :checkhealth vim.lsp, the new config is listed under "Enabled Configurations". 😎

As a file

  1. Create a file after/lsp/foo.lua somewhere on your 'runtimepath'.
    :exe 'edit' stdpath('config') .. '/after/lsp/foo.lua'
  2. Add this code to the file (or copy any of the examples from the lsp/ directory in this repo):
    return {
  cmd = { 'true' },
}
  3. Save the file (with ++p to ensure its parent directory is created).
    :write ++p
  4. Enable the config.
    :lua vim.lsp.enable('foo')
  5. Run :checkhealth vim.lsp, the new config is listed under "Enabled Configurations". 🌈

LSP Settings Type Annotations

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)

Troubleshooting

Start with :checkhealth vim.lsp to troubleshoot. The most common reasons a language server does not start or attach are:

  1. Language server is not installed. nvim-lspconfig does not install language servers for you. You should be able to run the cmd defined in the config from the command line and see that the language server starts. If the cmd is a name instead of an absolute path, ensure it is on your $PATH.

  2. 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.

  3. 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.lua at 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 exrc file is executed only if it's inside of a cwd where you start nvim.

Bug reports

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.

Contributions

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:

  1. Read CONTRIBUTING.md.
  2. Create a new file at lsp/<server_name>.lua.
  3. Ask questions on GitHub Discussions or in the Neovim Matrix room.

Release process

To publish a release:

License

Copyright Neovim contributors. All rights reserved.

nvim-lspconfig is licensed under the terms of the Apache 2.0 license.

See LICENSE.md

nvim-lspconfig (neovim/nvim-lspconfig)

Searching Database…

14K ·GitHub
Nvim-lspconfig
What is this?nvim-lspconfig is a collection of ready-made LSP server configurations for Neovim's built-in LSP client, so you don't have to hand-write the setup for each language server.
Is this a plugin or a full LSP client?It's just configuration data, not a client or a language server itself — Nvim's built-in LSP client does the actual work, this repo only ships the per-server settings (command, root markers, filetypes).
How do I get it running?Install a language server (e.g. pyright), enable its config in your init.lua with vim.lsp.enable('...'), open a file in a project with a recognizable root marker, and Nvim will attach LSP automatically.
Do I need a specific Neovim version?Yes — it requires Nvim 0.11.3+, and the legacy require('lspconfig') API is deprecated in favor of vim.lsp.config/vim.lsp.enable introduced in 0.11+; 0.10 support is being dropped.
Does it install language servers for me?No. You must install each language server yourself (and make sure its command is on your $PATH); nvim-lspconfig only supplies the configuration that tells Nvim how to launch and talk to it.
Does it work the same on Linux, macOS and Windows?Yes, it's pure Lua configuration that runs on any platform Neovim itself supports.
How do I debug a server that won't attach?Run :checkhealth vim.lsp first, then check root markers, filetype detection, and enable verbose logging in init.lua before inspecting the output of :LspLog.
Can I override or extend a server's default config?Yes, use vim.lsp.config('name', {...}) to extend an existing config, or place an after/lsp/name.lua file on your runtimepath to override the defaults with your own settings.
Where do I see the full list of supported servers?Run :help lspconfig-all from inside Nvim, or browse the configs documented in the repo's configs.md.
Why is require('lspconfig').setup{} deprecated?Neovim 0.11+ moved this functionality into the core vim.lsp.config and vim.lsp.enable APIs, so the old lua/lspconfig/ module is being phased out in favor of the lsp/ directory configs that vim.lsp.config auto-discovers.
What are similar projects?neovim, ale, LunarVim, lazy.nvim, telescope.nvim, vimrc, NvChad, AstroNvim
Which topics is it in?language-server, nvim, language-server-protocol, lsp, neovim, configuration, lua, vim, editor, command-line, plugin, terminal
Creator
neovim
Size
8.5 MB
Stars
14K
Updated
CommitOct 16Releasev2.12.0Sep 23
Age
6y
Commits · 90 Days