M-x Eglot

Emacs Polyglot: an Emacs LSP client that stays out of your way:

📽 Scroll down this README for some pretty gifs
📚 Read about:
📣 Read the NEWS file
🏆 Folks over at Google seem to like it. Thanks!

1-2-3

Install from GNU ELPA or MELPA. Just type M-x package-install RET eglot RET into Emacs 26.1+.

Now find some source file, any source file, and type M-x eglot.

That's it. If you're lucky, this guesses the LSP program to start for the language you're using. Otherwise, it prompts you to enter one.

1-2-3-pitfall!

By design, Eglot doesn't depend on anything but Emacs. But there are ELPA dependencies to newer versions of so-called "core packages" developed in the Emacs mainline. So unless you're using a bleeding-edge Emacs, where loading eglot.el is all you'd need to do, make sure your package system pulls in and loads the newest project.el, xref.el, eldoc.el, etc... In case of trouble M-x find-library can help you tell if that happened.

Connecting to a server

M-x eglot can guess and work out-of-the-box with these servers:

Ada's ada_language_server
Bash's bash-language-server
C/C++'s clangd or ccls
C#'s omnisharp
Clojure's clojure-lsp
CMake's cmake-language-server
CSS's css-languageserver
Dart's analysis_server
Dockerfile's docker-langserver
Elixir's elixir-ls
Elm's elm-language-server
Erlang's erlang_ls
Fortran's fortls
Futhark's futhark lsp
Go's gopls
Godot Engine's built-in LSP
HTML html-languageserver
Haskell's haskell-language-server
JSON's vscode-json-languageserver
Java's Eclipse JDT Language Server
Javascript's TS & JS Language Server
Kotlin's kotlin-language-server
Lua's lua-lsp
Markdown's marksman
Mint's mint-ls
Nix's rnix-lsp
Ocaml's ocaml-lsp
Perl's Perl::LanguageServer
PHP's php-language-server
PureScript's purescript-language-server
Python's pylsp, pyls pyright, or jedi-language-server
R's languageserver
Racket's racket-langserver
Ruby's solargraph
Rust's rust-analyzer
Scala's metals
TeX/LaTeX's Digestif
VimScript's vim-language-server
YAML's yaml-language-server
Zig's zls

I'll add to this list as I test more servers. In the meantime you can customize eglot-server-programs:

(add-to-list 'eglot-server-programs '(foo-mode . ("foo-language-server" "--args")))

Let me know how well it works and we can add it to the list.

To skip the guess and always be prompted use C-u M-x eglot.

Connecting automatically

You can also do:

  (add-hook 'foo-mode-hook 'eglot-ensure)

, to attempt to start an eglot session automatically every time a foo-mode buffer is visited.

Connecting via TCP

The examples above use a "pipe" to talk to the server, which works fine on Linux and OSX but in some cases may not work on Windows.

To circumvent this limitation, or if the server doesn't like pipes, you can use C-u M-x eglot and give it server:port pattern to connect to a previously started TCP server serving LSP information.

If you don't want to start it manually every time, you can configure Eglot to start it and immediately connect to it. Ruby's solargraph server already works this way out-of-the-box.

For another example, suppose you also wanted start Python's pyls this way:

(add-to-list 'eglot-server-programs
             `(python-mode . ("pyls" "-v" "--tcp" "--host"
                              "localhost" "--port" :autoport)))

You can see that the element associated with python-mode is now a more complicated invocation of the pyls program, which requests that it be started as a server. Notice the :autoport symbol in there: it is replaced dynamically by a local port believed to be vacant, so that the ensuing TCP connection finds a listening server.

`eglot-workspace-configuration`

Many servers can guess good defaults and operate nicely out-of-the-box, but some need to know project-specific settings, which LSP calls "workspace configuration".

Within Eglot, these per-project settings are realized with the Elisp variable eglot-workspace-configuration. They are sent over to the server:

initially, as a didChangeConfiguration notification;
as the response to configuration request from the server.

How to set (and whether to set it at all)

Before considering what to set the variable to, one must understand how to set it and whether to set it at all.

Most servers can be configured globally using some kind of global file in the user's home directory or in the project directory -- Pylsp reads ~/.config/pycodestyle and Clangd reads .clangd anywhere up the current project tree.

This type of configuration is done completely independently from Eglot and Emacs and has the advantage that it'll work with other LSP clients.

On the other hand, one may find this not flexible enough or wish to consolidate all configuration within Emacs.

In that case, the directory variable eglot-workspace-configuration should be used.

Note that while it is possible to set this variable globally or buffer-locally, doing so makes little sense. It is usually set via .dir-locals.el or special-purpose elisp functions.

Format of the value

The recommended format for this variable's value is a property list:

(SECTION-1 PARAM-OBJECT-1 ... SECTION-N PARAM-OBJECT-N)

(Yes, earlier it used to be an association list, a format that is still supported, but discouraged.)

Each SECTION-N is an Elisp keyword naming a parameter section relevant to an LSP server.

PARAM-OBJECT-N contains one or more settings pertaining to the server that is interested in SECTION-N. Its value is an Elisp object serialized to JSON by json-serialize. The recommended format is again a plist, though json-serialize also accepts other formats.

In any case, the JSON values true, false and {} are represented by the Elisp values t, :json-false and nil, respectively.

When experimenting with settings, one may use M-x eglot-show-workspace-configuration to inspect/debug the definite JSON value sent over to the server. This helper function works even before actually connecting to the server.

Simple example

To make a particular Python project always enable Pylsp's snippet support, put a file named .dir-locals.el in the project's root:

((python-mode
  . ((eglot-workspace-configuration
      .
      ;; the value in the format described above starts here
      (:pylsp (:plugins (:jedi_completion (:include_params t
                                           :fuzzy t)
                         :pylint (:enabled :json-false))))
      ;; and ends here
      ))))

This tells Emacs that any python-mode buffers in that directory should have a particular value of eglot-workspace-configuration.

Here, the value in question associates the parameter section :pylsp with a parameter object that is a plist of plists. It is converted to JSON before being sent to the server:

{
  "pylsp": {
    "plugins": {
      "jedi_completion": { "include_params": true, "fuzzy": true },
      "pylint": { "enabled": false }
    }
  }
}

Multiple servers

Suppose one also has some Go code in the very same project, the Gopls server can be configured in the same .dir-locals.el file. Adding a section for go-mode, the file's contents now become:

((python-mode
  . ((eglot-workspace-configuration
      . (:pylsp (:plugins (:jedi_completion (:include_params t
                                             :fuzzy t)
                           :pylint (:enabled :json-false)))))))
 (go-mode
  . ((eglot-workspace-configuration
      . (:gopls (:usePlaceholders t))))))

Alternatively, as a matter of taste, one may choose to lay out .dir-locals.el like so:

((nil
  . ((eglot-workspace-configuration
      . (:pylsp (:plugins (:jedi_completion (:include_params t
                                             :fuzzy t)
                           :pylint (:enabled :json-false)))
         :gopls (:usePlaceholders t))))))

This is an equivalent setup which sets the value in all major-modes inside the project: the major-mode specification is unneeded because the LSP server will retrieve only the parameter section it is interested in.

Setting the value without `.dir-locals.el`

If adding a .dir-locals.el file isn't suitable, or if managing this file becomes cumbersome, the Emacs manual teaches you programmatic ways to leverage per-directory local variables. Look for the functions dir-locals-set-directory-class and dir-locals-set-class-variables.

Dynamically setting the value

If one needs to determine the workspace configuration based on some dynamic context, eglot-workspace-configuration can be set to a function. It is passed the eglot-lsp-server instance of the connected server (if any) and runs with default-directory set to the root of your project. The function should return a value of the same form as described in the previous paragraphs.

Handling quirky servers

Some servers need even more special hand-holding to operate correctly. If your server has some quirk or non-conformity, it's possible to extend Eglot via Elisp to adapt to it. Here's an example on how to get cquery working:

(add-to-list 'eglot-server-programs '((c++ mode c-mode) . (eglot-cquery "cquery")))

(defclass eglot-cquery (eglot-lsp-server) ()
  :documentation "A custom class for cquery's C/C++ langserver.")

(cl-defmethod eglot-initialization-options ((server eglot-cquery))
  "Passes through required cquery initialization options"
  (let* ((root (car (project-roots (eglot--project server))))
         (cache (expand-file-name ".cquery_cached_index/" root)))
    (list :cacheDirectory (file-name-as-directory cache)
          :progressReportFrequencyMs -1)))

Similarly, some servers require the language identifier strings they are sent by eglot to match the exact strings used by VSCode. eglot usually guesses these identifiers from the major mode name (e.g. elm-mode → "elm"), but the mapping can be overridden using the :LANGUAGE-ID element in the syntax of eglot-server-programs if necessary.

TRAMP support

Should just work. Try M-x eglot in a buffer visiting a remote file on a server where you've also installed the language server. Only supported on Emacs 27.1 or later.

Emacs 27 users may find some language servers fail to start up over TRAMP. If you experience this issue, update TRAMP to 2.5.0.4 or later.

Reporting bugs

Having trouble connecting to a server? Expected to have a certain capability supported by it (e.g. completion) but nothing happens? Or do you get spurious and annoying errors in an otherwise smooth operation? We may have help, so open a new issue and try to be as precise and objective about the problem as you can:

Include the invaluable events transcript. You can display that buffer with M-x eglot-events-buffer. It contains the JSONRPC messages exchanged between client and server, as well as the messages the server prints to stderr.
If Emacs errored (you saw -- and possibly heard -- an error message), make sure you repeat the process using M-x toggle-debug-on-error so you get a backtrace of the error that you should also attach to the bug report.
Try to replicate the problem with as clean an Emacs run as possible. This means an empty .emacs init file or close to it (just loading eglot.el, company.el and yasnippet.el for example, and you don't even need use-package.el to do that).

Some more notes: it is often the case the you will have to report the problem to the LSP server's developers, too, though it's understandable that you report it Eglot first, since it is the user-facing frontend first. If the problem is indeed on Eglot's side, we do want to fix it, but because Eglot's developers have limited resources and no way to test all the possible server combinations, you'll sometimes have to do most of the testing.

Commands and keybindings

Here's a summary of available commands:

M-x eglot, as described above;
M-x eglot-reconnect reconnects to current server;
M-x eglot-shutdown says bye-bye to server of your choice;
M-x eglot-shutdown-all says bye-bye to every server;
M-x eglot-rename ask the server to rename the symbol at point;
M-x eglot-format asks the server to format buffer or the active region;
M-x eglot-code-actions asks the server for any "code actions" at point. Can also be invoked by mouse-1-clicking some diagnostics. Also M-x eglot-code-action-<TAB> for shortcuts to specific actions.
M-x eldoc asks the Eldoc system for help at point (this command isn't specific to Eglot, by the way, it works in other contexts).
M-x eglot-events-buffer jumps to the events buffer for debugging communication with the server.
M-x eglot-stderr-buffer if the LSP server is printing useful debug information in stderr, jumps to a buffer with these contents.
M-x eglot-signal-didChangeConfiguration updates the LSP server configuration according to the value of the variable eglot-workspace-configuration, which you may be set in a .dir-locals file, for example.

There are no keybindings specific to Eglot, but you can bind stuff in eglot-mode-map, which is active as long as Eglot is managing a file in your project. The commands don't need to be Eglot-specific, either:

(define-key eglot-mode-map (kbd "C-c r") 'eglot-rename)
(define-key eglot-mode-map (kbd "C-c o") 'eglot-code-action-organize-imports)
(define-key eglot-mode-map (kbd "C-c h") 'eldoc)
(define-key eglot-mode-map (kbd "<f6>") 'xref-find-definitions)

Customization

Here's a quick summary of the customization options. In Eglot's customization group (M-x customize-group) there is more documentation on what these do.

eglot-autoreconnect: Control ability to reconnect automatically to the LSP server;
eglot-connect-timeout: Number of seconds before timing out LSP connection attempts;
eglot-sync-connect: Control blocking of LSP connection attempts;
eglot-events-buffer-size: Control the size of the Eglot events buffer;
eglot-ignored-server-capabilities: LSP server capabilities that Eglot could use, but won't;
eglot-confirm-server-initiated-edits: If non-nil, ask for confirmation before allowing server to edit the source buffer's text;

There are a couple more variables that you can customize via Emacs lisp:

eglot-server-programs: as described above;
eglot-strict-mode: Set to nil by default, meaning Eglot is generally lenient about non-conforming servers. Set this to (disallow-non-standard-keys enforce-required-keys) when debugging servers.
eglot-server-initialized-hook: Hook run after server is successfully initialized;
eglot-managed-mode-hook: Hook run after Eglot started or stopped managing a buffer. Use eglot-managed-p to tell if current buffer is still being managed.
eglot-stay-out-of: List of Emacs features that Eglot shouldn't automatically try to manage on users' behalf. Useful when you need non-LSP Flymake or Company backends. See docstring for examples.
eglot-extend-to-xref: If non-nil and xref-find-definitions lands you in a file outside your project -- like a system-installed library or header file -- transiently consider it managed by the same LSP server. That file is still outside your project (i.e. project-find-file won't find it).

How does Eglot work?

M-x eglot starts a server via a shell-command guessed from eglot-server-programs, using the current major-mode (for whatever language you're programming in) as a hint.

If the connection is successful, you see an [eglot:<server>] indicator pop up in your mode-line. More importantly, this means current and future file buffers of that major mode inside your current project automatically become "managed" by the LSP server, This means that information about these file's contents is exchanged periodically to provide enhanced coding assistance. Eglot works primarily with Emacs' built-in libraries and not with third-party replacements for those facilities.

definitions can be found via xref-find-definitions;
on-the-fly diagnostics for the buffer or project are given by flymake-mode;
function signature hints are given by eldoc-mode;
completion can be summoned with completion-at-point.
projects are discovered via project.el's API;

Some extra features are provided if certain libraries are installed and enabled, such as:

completion dropdowns via company;
snippet completions via yasnippet;
marked-up documentation via markdown.

Eglot doesn't require these libraries to work effectively, but will use them automatically if they are found to be active.

To "unmanage" a project's buffers, shutdown the server with M-x eglot-shutdown.

Obligatory animated gif section

Completion

The animation shows company-mode presenting the completion candidates to the user, but Eglot works with the built-in completion-at-point function as well, which is usually bound to C-M-i.

Snippet completion

Eglot provides template based completion if the server supports snippet completion and yasnippet is enabled before Eglot connects to the server. The animation shows company-mode, but completion-at-point also works with snippets.

Diagnostics

Eglot relays the diagnostics information received from the LSP server to Emacs's Flymake, which annotates/underlines the problematic parts of the buffer. The information is shared with the ElDoc system, meaning that the commands eldoc and eldoc-doc-buffer (the latter bound to C-h-. for convenience) show diagnostics along with other documentation under point.

Flymake provides other convenient ways to view and manage diagnostic errors. These are described in its manual.

When Eglot manages a buffer, it disables pre-existing Flymake backends. See variable eglot-stay-out-of to change that.

Code Actions

The LSP server may provide code actions, for example, to fix a diagnostic error or to suggest refactoring edits. The commands are frequently associating with Flymake diagnostic annotations, so that left-clicking them shows a menu. Additionally, the command eglot-code-actions asks the server for any code spanning a given region.

Sometimes, these code actions are initiated by the server. See eglot-confirm-server-initiated-edits to control that behaviour.

Hover on symbol /function signature

Here, too, the LSP server's view of a given symbol or function signature is relayed to the ElDoc system. The commands eldoc and eldoc-doc-buffer commands access that information.

There are customization variables to help adjust ElDoc's liberal use of the lower "echo area", among other options. If you still find the solicitous nature of this LSP feature too distracting, you can use eglot-ignored-server-capabilities to turn it off.

Rename

Type M-x eglot-rename RET to rename the symbol at point.

Find definition

To jump to the definition of a symbol, use the built-in xref-find-definitions command, which is bound to M-..

Find references

Eglot here relies on Emacs' built-in functionality as well. xref-find-references is bound to M-?. Additionally, Eglot provides the following similar commands: eglot-find-declaration, eglot-find-implementation, eglot-find-typeDefinition.

Historical differences to lsp-mode.el

Around May 2018, I wrote a comparison of Eglot to lsp-mode.el, and was discussed with its then-maintainer. That mode has since been refactored/rewritten and now purports to support a lot of features that differentiated Eglot from it. It may now be very different or very similar to Eglot, or even sing with the birds in the trees, so go check it out. That said, here's the original comparison, which I will not be updating any more.

"Eglot is considerably less code and hassle than lsp-mode.el. In most cases, there's nothing to configure. It's a minimalist approach focused on user experience and performance.

User-visible differences:

The single most visible difference is the friendly entry point M-x eglot, not M-x eglot-<language>. Also, there are no eglot-<language> extra packages.
There's no "whitelisting" or "blacklisting" directories to languages. M-x eglot starts servers to handle file of a major mode inside a specific project, using Emacs's built-in project.el library to discover projects. Then it automatically detects current and future opened files under that project and syncs with server;
Easy way to quit/restart a server, just middle/right click on the connection name;
Pretty interactive mode-line section for live tracking of server communication;
Automatically restarts frequently crashing servers;
Slow-to-start servers start asynchronously in the background;
Server-initiated edits are confirmed with the user;
Diagnostics work out-of-the-box (no flycheck.el needed);
Smoother/more responsive (read below).

Under the hood:

Message parser is much simpler.
Defers signature requests like textDocument/hover until server is ready.
Sends textDocument/didChange for groups of edits, not one per each tiny change.
Easier to read and maintain elisp. Yeah I know, very subjective, so judge for yourself.
Doesn't require anything other than Emacs, but will automatically upgrade to work with stuff outside Emacs, like company, markdown-mode, if you happen to have these installed.
Has automated tests that check against actual LSP servers."

Copyright Assignment

Eglot is subject to the same copyright assignment policy as GNU Emacs.

Any legally significant contributions can only be merged after the author has completed their paperwork. Please ask for the request form, and we'll send it to you.

danilevy1212 / eglot

M-x Eglot

1-2-3

1-2-3-pitfall!

Connecting to a server

Connecting automatically

Connecting via TCP

`eglot-workspace-configuration`

How to set (and whether to set it at all)

Format of the value

Simple example

Multiple servers

Setting the value without `.dir-locals.el`

Dynamically setting the value

Handling quirky servers

TRAMP support

Reporting bugs

Commands and keybindings

Customization

How does Eglot work?

Obligatory animated gif section

Completion

Snippet completion

Diagnostics

Code Actions

Hover on symbol /function signature

Rename

Find definition

Find references

Historical differences to lsp-mode.el

Copyright Assignment

About

Languages

M-x Eglot

1-2-3

1-2-3-pitfall!

Connecting to a server

Connecting automatically

Connecting via TCP

eglot-workspace-configuration

How to set (and whether to set it at all)

Format of the value

Simple example

Multiple servers

Setting the value without .dir-locals.el

Dynamically setting the value

Handling quirky servers

TRAMP support

Reporting bugs

Commands and keybindings

Customization

How does Eglot work?

Obligatory animated gif section

Completion

Snippet completion

Diagnostics

Code Actions

Hover on symbol /function signature

Rename

Find definition

Find references

Historical differences to lsp-mode.el

Copyright Assignment

About

Languages

`eglot-workspace-configuration`

Setting the value without `.dir-locals.el`