1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
# nvim-lspconfig
nvim-lspconfig is a "data only" repo, providing basic, default [Nvim LSP client](https://neovim.io/doc/user/lsp.html)
configurations for various LSP servers. View [all configs](doc/configs.md) or `:help lspconfig-all` from Nvim.
## Important ⚠️
* These configs are **best-effort and supported by the community (you).** See [contributions](#contributions).
* The configs live in [`lsp/`](./lsp/).
* Upgrade to Nvim 0.11+ and use `vim.lsp.enable('…')` (not `require'…'.pyright.setup{}`) to enable a config.
* The configs in `lua/lspconfig/` are *deprecated* and will be removed.
* Upgrade to Nvim 0.11+ and use `vim.lsp.enable('…')` (not `require'…'.pyright.setup{}`) to enable a config.
* Ask questions on [GitHub Discussions](https://github.com/neovim/neovim/discussions), not the issue tracker.
* If you found a bug in Nvim LSP (`:help lsp`), [report it to Neovim core](https://github.com/neovim/neovim/issues/new?assignees=&labels=bug%2Clsp&template=lsp_bug_report.yml).
* **Do not** report it here. Only configuration data lives here.
* This repo only provides *configurations*. Its programmatic API is deprecated and must not be used externally.
* The "framework" parts (*not* the configs) of nvim-lspconfig [will be upstreamed to Nvim core](https://github.com/neovim/neovim/issues/28479).
## Install
[](https://luarocks.org/modules/neovim/nvim-lspconfig)
* Requires Nvim 0.10 above. Update Nvim and nvim-lspconfig before reporting an issue.
* 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 (consult the documentation for your plugin manager).
## Quickstart
1. Install a language server, e.g. [pyright](doc/configs.md#pyright)
```bash
npm i -g pyright
```
2. Add the language server setup to your init.lua.
- Nvim 0.11+ (see [vim.lsp.config](#vimlspconfig))
```lua
vim.lsp.enable('pyright')
```
- Nvim 0.10 (legacy, **not supported**)
```lua
require'lspconfig'.pyright.setup{}
```
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 lsp` to see the status or to troubleshoot.
Read `:help lspconfig` for details. Read `: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, see [vim.lsp.config](#vimlspconfig).
## Configuration
Nvim sets default options and mappings when LSP is active in a buffer:
* [:help lsp-defaults](https://neovim.io/doc/user/lsp.html#lsp-defaults).
* [:help diagnostic-defaults](https://neovim.io/doc/user/diagnostic.html#diagnostic-defaults)
To customize, see:
* [:help lsp-attach](https://neovim.io/doc/user/lsp.html#lsp-attach)
* [`:h lsp-buf`][lsp-buf]
Extra settings can be specified for each LSP server:
- Nvim 0.11+ (see [vim.lsp.config](#vimlspconfig))
```lua
vim.lsp.config('rust_analyzer', {
-- Server-specific settings. See `:help lsp-quickstart`
settings = {
['rust-analyzer'] = {},
},
})
```
- Nvim 0.10 (legacy, **not supported**)
```lua
local lspconfig = require('lspconfig')
lspconfig.rust_analyzer.setup {
-- Server-specific settings. See `:help lspconfig-setup`
settings = {
['rust-analyzer'] = {},
},
}
```
## vim.lsp.config
`nvim-lspconfig` configs live in [`lsp/`](./lsp/). Using Nvim 0.11 or newer, you can `enable()` a config: it will auto-activate when a filetype is opened.
Example:
```lua
vim.lsp.enable('pyright')
```
and configured with:
```lua
vim.lsp.config('pyright', {
cmd = { … },
})
```
which extends the configuration under [`lsp/`](./lsp/). For further information see [`:help lsp-config`][lsp-config].
## Troubleshooting
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 each server's Lua module from the command line and see that the language server starts. If the `cmd` is an executable name instead of an absolute path to the executable, ensure it is on your path.
2. Missing filetype plugins. Certain languages are not detected by Vim/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 [doc/configs.md](doc/configs.md).
## Bug reports
If you found a bug with LSP functionality, [report it to Neovim core](https://github.com/neovim/neovim/issues/new?assignees=&labels=bug%2Clsp&template=lsp_bug_report.yml).
Before reporting a bug, check your logs and the output of `:LspInfo`. Add the following to your init.vim to enable logging:
```lua
vim.lsp.set_log_level("debug")
```
Attempt to run the language server, and open the log with:
```
:LspLog
```
Most of the time, the reason for failure is present in the logs.
## Commands
* `:LspInfo` (alias to `:checkhealth vim.lsp`) shows the status of active and configured language servers.
* `:LspStart <config_name>` Start the requested server name. Will only successfully start if the command detects a root directory matching the current config.
* `:LspStop [<client_id_or_name>]` Stops the given server. Defaults to stopping all servers active on the current buffer. To force stop add `++force`
* `:LspRestart [<client_id_or_name>]` Restarts the given client, and attempts to reattach to all previously attached buffers. Defaults to restarting all active servers.
## Contributions
If a language server is missing from [configs.md](doc/configs.md), contributing
a new configuration for it helps others, especially if the server requires special setup. Follow these steps:
1. Read [CONTRIBUTING.md](CONTRIBUTING.md).
2. Create a new file at `lsp/<server_name>.lua`.
- Copy an [existing config](https://github.com/neovim/nvim-lspconfig/tree/master/lsp)
to get started. Most configs are simple. For an extensive example see
[texlab.lua](https://github.com/neovim/nvim-lspconfig/blob/master/lsp/texlab.lua).
3. Ask questions on [GitHub Discussions](https://github.com/neovim/neovim/discussions) or in the [Neovim Matrix room](https://app.element.io/#/room/#neovim:matrix.org).
## Release process
To publish a release:
- Create and push a new [tag](https://github.com/neovim/nvim-lspconfig/tags).
- After pushing the tag, a [GitHub action](./.github/workflows/release.yml)
will automatically package the plugin and publish the release to LuaRocks.
## License
Copyright Neovim contributors. All rights reserved.
nvim-lspconfig is licensed under the terms of the Apache 2.0 license.
See [LICENSE.md](./LICENSE.md)
|
