Skip to content


Repository files navigation

lsp-mode uses lsp-docker to run language servers using in containers


Table of Contents

Preconfigured language servers

emacslsp/lsp-docker-langservers has the following content:


There are two ways of working with containerized language servers:


This container is used by lsp-docker to run Language Servers for lsp-mode over local sources. You must pull the container before lsp-docker can use it


  • Clone the repo
    git clone
  • Pull the container
    docker pull emacslsp/lsp-docker-langservers
  • Add repo to load path and register the docker clients in your ~/.emacs file
    ;; Uncomment the next line if you are using this from source
    ;; (add-to-list 'load-path "<path-to-lsp-docker-dir>")
    (require 'lsp-docker)
    (defvar lsp-docker-client-packages
        '(lsp-css lsp-clients lsp-bash lsp-go lsp-pylsp lsp-html lsp-typescript
          lsp-terraform lsp-clangd))
    (setq lsp-docker-client-configs
        '((:server-id bash-ls :docker-server-id bashls-docker :server-command "bash-language-server start")
          (:server-id clangd :docker-server-id clangd-docker :server-command "clangd")
          (:server-id css-ls :docker-server-id cssls-docker :server-command "css-languageserver --stdio")
          (:server-id dockerfile-ls :docker-server-id dockerfilels-docker :server-command "docker-langserver --stdio")
          (:server-id gopls :docker-server-id gopls-docker :server-command "gopls")
          (:server-id html-ls :docker-server-id htmls-docker :server-command "html-languageserver --stdio")
          (:server-id pylsp :docker-server-id pyls-docker :server-command "pylsp")
          (:server-id ts-ls :docker-server-id tsls-docker :server-command "typescript-language-server --stdio")))
    (require 'lsp-docker)
      :path-mappings '(("path-to-projects-you-want-to-use" . "/projects"))
      :client-packages lsp-docker-client-packages
      :client-configs lsp-docker-client-configs)

How it works

lsp-mode starts the image passed as :docker-image-id and mounts :path-mappings in the container. Then when the process is started lsp-mode translates the local paths to docker path and vice versa using the :path-mappings specified when calling lsp-docker-init-default-clients. You may use lsp-enabled-clients and lsp-disabled-clients to control what language server will be used to run for a particular project(refer to lsp-mode FAQ on how to configure .dir-locals).


The container emacslsp/lsp-docker-full contains:

  • The above language servers
  • Emacs28 compiled with native JSON support for better performance.


EMACS_D_VOLUMEEmacs folder to use for /root/.emacsEmacs: $(pwd)/emacs.d Spacemacs: $(pwd)/spacemacs
PROJECTS_VOLUMEDirectory to mount at /Projects$(pwd)/demo-projects/
TZTimezone to user in containerEurope/Minsk
DOCKER_FLAGSAny additional docker flagsN/A


  • Clone lsp-docker.
    git clone
    cd lsp-docker
  • Run


  • Clone lsp-docker.
    git clone
    cd lsp-docker
  • Clone spacemacs repo
    # Clone spacemacs develop
    git clone -b develop spacemacs
  • Run
    EMACS_D_VOLUME=/path/to/spacemacs bash

Custom language server containers

You can use manually built language containers or images hosting language server(s), just follow a few simple rules (shown below). The docker images may feature an optional tag, if omitted latest will be assumed.

Building a container (or an image) manually:

You have 2 constraints:

  • A language server must be launched in stdio mode (other types of communication are yet to be supported)
  • A docker container (only container subtype, see the configuration below) must have your language server as an entrypoint (basically you have to be able to launch it with docker start -i <container_name> as it is launched this way with lsp-docker)

When you have sucessfully built a language server, you have to register it with either a configuration file or a .dir-locals file.

Registering a language server using a persistent configuration file:

A configuration file is a yaml file that can be located at:


It is structured in the following way:

# single server configuration
    type: docker
    # subtype:
    # - "container": attach to an already running container
    # - "image": when image does not exist, try to build it based on the dockerfile found in the project-scope
    #   (see Automatic image building). An image might feature an optional tag, i.e. '<image>:<tag>'. If a
    #   tagless image is indicated 'latest' will be assumed.
    subtype: container
    # Image/container name to use for this language server.
    name: image-container-name
    # server id of a registered LSP server. You can find the list of registered servers evaluating:
    # `(ht-keys lsp-clients)`
    # source:
    server: server-id-of-the-base-server
    # an (optional) array of parameters (docker or podman) to launch the image with
    # initially intended to host the '--userns' parameter
    # NOTE: 'launch_parameters' are not used with 'container' subtype servers
    # in this case embed all required parameters when creating the server instead
      - "--userns=nomap"
    # command to launch the language server in stdio mode
    # NOTE: 'launch_command' is not used with 'container' subtype servers as a command is embedded in a
    # container itself and serves as entrypoint
    launch_command: "launch command with arguments"
    # NOTE: the paths must be within the project this server is being build for
    - source: "/your/host/source/path"
      destination: "/your/path/inside/the/container"

# multiple server configuration
    - type: ...
      subtype: ...
      ...                       # keys as in the classic single server case, e.g. type, subtype, etc...
    - ...                       # other single server configuration(s)
  mappings:                     # shared among all servers
    - source: <path-on-host>
      destination: <path-on-lang-server>
    ...                         # other mappings

Registering a language server using a .dir-locals file:

Just refer to the source code and general conventions of using .dir-locals. The variable you need is lsp-docker-persistent-default-config, its content is merged with the lsp section from a configuration file (if present).

Automatic image building:

You can also build an image automatically (currently supported only for image subtype): just drop the corresponding Dockerfile into the .lsp-docker folder in the project root (Dockerfile may be named as Dockerfile or Dockerfile.lsp). Building process is triggered by the lsp-docker-register call (you will be prompted whether you want to build the image). Image building takes place in the project root (not in the .lsp-docker subfolder)! In case of an automatic build the image will be registered automatically (based on the values from the config or .dir-locals file).

You can also troubleshoot any issues with supplemental docker calls (checking whether the required image already exists, building a new image) using the supplemental logging functionality: there are 2 variables: first you have to set lsp-docker-log-docker-supplemental-calls to true-like value (by default it is nil) and then specify the log buffer in the lsp-docker-log-docker-supplemental-calls-buffer-name variable (by default it is set to *lsp-docker-supplemental-calls*)

Docker over TRAMP (TBD)

Docker running the language servers and hosting the sources, Emacs running on the desktop machine and connecting to docker instance over TRAMP.

See also

  • docker - package for managing docker images/containers.