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
200
201
202
203
204
205
206
207
208
209
210
211
212
|
*lspconfig.txt* For Nvim version 0.10+
nvim-lspconfig provides user-contributed configs for the Nvim |lsp| client.
Type |gO| to see the table of contents.
==============================================================================
INTRODUCTION *lspconfig*
nvim-lspconfig is a collection of community-contributed configurations for the
Nvim LSP client. See |lspconfig-all| for the complete list of provided
configurations.
Note: nvim-lspconfig is just a collection of configs. It has no API or
"framework". It is not required for Nvim |LSP| support. See |lsp-quickstart|
to setup LSP without nvim-lspconfig.
==============================================================================
QUICKSTART *lspconfig-quickstart*
1. Install a language server, e.g. pyright. >bash
npm i -g pyright
2. Add the language server setup to your init.lua. >lua
vim.lsp.enable('pyright')
3. Ensure your workspace contains a root marker as specified in
|lspconfig-all|.
4. Open a code file in Nvim. LSP will attach and provide diagnostics. >bash
nvim main.py
5. Run `:checkhealth vim.lsp` to see the status or troubleshoot.
See also |lsp-quickstart|.
==============================================================================
USAGE *lspconfig-usage*
Each config provides defaults for |vim.lsp.config()| which you can use as-is
(by calling `vim.lsp.enable(…)`) or override (by calling |vim.lsp.config()|
before enable()). This "composability" is a central feature of vim.lsp.config,
which allows nvim-lspconfig to just provide the config "defaults".
To activate a config, call |vim.lsp.enable()|. Each config in |lspconfig-all|
is available as `vim.lsp.config('<name>')` and `vim.lsp.enable('<name>')`. For
example to activate the "clangd" config: >lua
-- Optionally override parts of the default config...
vim.lsp.config('clangd', {
…
})
-- Enable filetype-based activation of the config.
vim.lsp.enable('clangd')
<
*lspconfig-resolved*
You can call the "index" form of vim.lsp.config to get the resolved config
without activating it: >lua
vim.print(vim.lsp.config['clangd'])
<
*lspconfig-vs-vim.lsp.config*
Note these differences of |vim.lsp.config()| compared to the legacy
nvim-lspconfig interface:
- `single_file_support` is assumed by default. Can be disabled by specifying
`workspace_required=false` (see |vim.lsp.ClientConfig|).
- `on_new_config` is currently missing, see https://github.com/neovim/neovim/issues/32287
- However, defining `root_dir` as a function is very flexible and may fit
your use-case instead. https://github.com/neovim/neovim/issues/32037#issuecomment-2825599872
==============================================================================
COMMANDS *lspconfig-commands*
Any server-specific commands provided by a config are buffer-local and
prefixed with "Lsp". Thus you can see available commands (from a LSP-enabled
buffer) by typing: >vim
:Lsp<tab>
The following _global_ commands are provided by nvim-lspconfig:
:LspInfo *:LspInfo*
Alias to `:checkhealth vim.lsp`. Shows the status of active LSP clients and
servers.
:LspStart [config_name] *:LspStart*
Launches the requested (configured) client, but only if it successfully
resolves a root directory. Note: Defaults to all configured servers matching
the current buffer filetype.
:LspStop [client_id] or [config_name] *:LspStop*
Stops the server with the given client-id or config name. Defaults to
stopping all servers active on the current buffer. To force stop language
servers: >vim
:LspStop!
:LspRestart [client_id] or [config_name] *:LspRestart*
Restarts the client with the given client-id or config name, and attempts
to reattach to all previously attached buffers. Defaults to restarting all
active servers. To force stop language servers when restarting: >vim
:LspRestart!
==============================================================================
SERVER CONFIGS *lspconfig-configurations*
See |lspconfig-all| for the list of provided LSP configurations.
If a server is missing, you can define one easily via |vim.lsp.config()|
(requires Nvim 0.11+), see |lsp-config|.
------------------------------------------------------------------------------
NEW CONFIGS *lspconfig-new*
To create a new config, see |lsp-config| (requires Nvim 0.11+).
To contribute a config to nvim-lspconfig, see ../CONTRIBUTING.md.
==============================================================================
COMPLETION SUPPORT *lspconfig-completion*
See |lsp-completion|.
==============================================================================
Migrate to vim.lsp.config *lspconfig-nvim-0.11*
The "framework" part of nvim-lspconfig is DEPRECATED. The "configs" are NOT
deprecated, but were moved to the lsp/ directory so that |vim.lsp.config()|
automatically finds them.
This means:
- `require'lspconfig'[…]` must NOT be used. Use `vim.lsp.config(…)` instead.
- The `require'lspconfig'` quasi-framework will be DELETED, and is not
supported in Nvim 0.11+.
- The nvim-lspconfig configs (|lspconfig-all|) now live in "lsp/" instead of
"lua/lspconfig/".
- To use the configs, call `vim.lsp.config(…)` instead of `require'lspconfig'[…]`.
MIGRATION INSTRUCTIONS
To migrate:
- Upgrade to Nvim 0.11 or later.
- Change `require'lspconfig'[…]` to `vim.lsp.config(…)`.
- Some field names changed, see |lspconfig-vs-vim.lsp.config|.
- See |lsp-config| for details.
BACKGROUND
Since Nvim 0.11, nvim-lspconfig provides configs in its "lsp/" directory. The
old configs still exist in "lua/lspconfig/configs/" but are deprecated and
will be DELETED.
This means the "configs" role of nvim-lspconfig continues to be relevant, but
it is now a "data-only" repository instead of a "framework". The only change
needed from you, and from plugins, is to use the Nvim 0.11 `vim.lsp.config`
interface to setup LSP configs instead of the old `require'lspconfig'`
quasi-framework.
==============================================================================
DEBUGGING AND TROUBLESHOOTING *lspconfig-debugging*
See |lsp-log| to enable verbose logs.
While using language servers should be easy, debugging issues can be
challenging. First, it is important to identify the source of the issue, which
is typically (in rough order):
- the language server itself
- a plugin
- overrides in a user configuration
- the built-in client in Nvim core
- nvim-lspconfig
The first step in debugging is to test with a minimal configuration:
https://github.com/neovim/neovim/issues/new?assignees=&labels=bug%2Clsp&template=lsp_bug_report.yml
Historically, many problems are due to plugins or misconfiguration.
Should that fail, identifying which component is the culprit is challenging.
The following are the only categories of bugs that pertain to nvim-lspconfig.
- The root directory inferred for your project is wrong, or it should be
detected but is not due to a bug in the nvim-lspconfig path utilities.
- The server is launching, but you believe that the default settings,
initialization options, or command arguments are suboptimal and should be
replaced based on your understanding of the server documentation.
All bugs Nvim's built-in client should be reported to the Nvim core issue
tracker. All bugs pertaining to plugins should be reported to the respective
plugin. All missing features in a language server should be reported to the
upstream language server issue tracker.
For debugging nvim-lspconfig issues, the most common hurdles users face are:
- The language server is not installed or is otherwise not executable.
nvim-lspconfig does not install language servers for you. Ensure the `cmd`
defined in |lspconfig-all| is executable from the command line. If the
absolute path to the binary is not supplied in `cmd`, ensure it is on your
PATH.
- Missing filetype plugins. Certain languages are not detecting by
Vim/Nvim because they have not yet been added to the filetype detection
system. Ensure `:set ft?` shows the filetype and not an empty value.
- Not triggering root detection. nvim-lspconfig is built around the concept
of projects.
- Not triggering root detection. Some language servers will only start
if it is opened in a directory, or child directory, containing a file
which signals the *root* of the project. Most of the time, this is
a `.git` folder, but each server defines the root config in the lua file.
See |lspconfig-all| or the source code for the list of root directories.
- Misconfiguration. Often users will override `cmd`, `on_init`, or
`handlers`. Ensure that you debug by using a stock configuration to ensure
your customizations are not introducing issues.
|:LspInfo| provides an overview which can be useful for debugging.
==============================================================================
vim:tw=78:ts=8:ft=help:norl:
|
