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
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
# nvim-lspconfig
nvim-lspconfig is a collection of LSP server configurations for the [Nvim LSP client](https://neovim.io/doc/user/lsp.html).
View [all configs](doc/configs.md), or run `:help lspconfig-all` from Nvim.
## Important ⚠️
* `require('lspconfig')` (the legacy "framework" of nvim-lspconfig) [is **deprecated**](https://github.com/neovim/nvim-lspconfig/issues/3693) in favor of [vim.lsp.config](https://neovim.io/doc/user/lsp.html#lsp-config) (Nvim 0.11+).
* The [lspconfig.lua](./lua/lspconfig.lua) *module* will be dropped. Calls to `require('lspconfig')` will show a warning, which will later become an error.
* nvim-lspconfig itself is **NOT deprecated**. It provides server-specific configs.
* The configs live in the [lsp/](./lsp/) directory. `vim.lsp.config` automatically finds them and merges them with any local `lsp/*.lua` configs defined by you or a plugin.
* The old configs in [lua/lspconfig/](./lua/lspconfig/) are **deprecated** and will be removed.
### 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](#contributions).
* 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.
## Install
[](https://luarocks.org/modules/neovim/nvim-lspconfig)
* Requires Nvim 0.11.3+.
* Support for Nvim 0.10 [will be removed](https://github.com/neovim/nvim-lspconfig/issues/3693). Upgrade 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 with Nvim 0.12 (nightly), you can use the builtin `vim.pack` plugin manager:
```lua
vim.pack.add{
{ src = 'https://github.com/neovim/nvim-lspconfig' },
}
```
* Or use a 3rd-party plugin manager.
## Quickstart
1. Install a language server, e.g. [pyright](doc/configs.md#pyright)
```bash
npm i -g pyright
```
2. Enable its config in your init.lua ([:help lsp-quickstart](https://neovim.io/doc/user/lsp.html#lsp-quickstart)).
```lua
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:
```lua
vim.lsp.config('jdtls', {
cmd = { '/path/to/jdtls' },
})
```
## 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)
* [:help lsp-buf](https://neovim.io/doc/user/lsp.html#lsp-buf)
Extra settings can be specified for each LSP server. With Nvim 0.11+ you can
[extend a config](https://neovim.io/doc/user/lsp.html#lsp-config) by calling
`vim.lsp.config('…', {…})`.
```lua
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](./lsp/) 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". 🌈
## 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:
```lua
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](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 `:checkhealth vim.lsp`. Add this to your init.lua to enable verbose logging:
```lua
vim.lsp.set_log_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.
## Commands
* `:LspInfo` (alias to `:checkhealth vim.lsp`) shows the status of active and configured language servers.
* `:lsp enable [<config_name>]` (`:LspStart` for 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>]` (`:LspStop` for 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>]` (`:LspRestart` for Nvim 0.11 or older) 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)
|
