Frequently Asked Questions (FAQ)


How do I install clangd?

Clangd is often distributed either within LLVM packages or in a separate Clang-related packages (e.g. clang-tools on Ubuntu). These packages (mostly) follow official LLVM releases, which are released once every 6 months.

If you want to use new versions of clangd, you have several options:

How do I check the clangd version I am using?

Can you give an example configuration file for clangd?

The preferred way to store clangd configuration is through YAML files. Here’s an example config you could use:

  # Treat code as C++, use C++17 standard, enable more warnings.
  Add: [-xc++, -std=c++17, -Wall, -Wno-missing-prototypes]
  # Remove extra warnings specified in compile commands.
  # Single value is also acceptable, same as "Remove: [-mabi]"
  Remove: -mabi
  # Tweak Clang-Tidy checks.
    Add: [performance*, modernize*, readability*]
    Remove: [modernize-use-trailing-return-type]
      readability-identifier-naming.VariableCase: CamelCase
# Use Remote Index Service for LLVM.
  # Note: This is a regexp, notice '.*' at the end of PathMatch string.
  PathMatch: /path/to/llvm/.*
    MountPoint: /path/to/llvm/

How do I build clangd from sources?

If you are a developer or downloading pre-built binaries is not an option, you can compile clangd from LLVM sources. Follow Getting Started instructions and make sure LLVM_ENABLE_PROJECTS has clang;clang-tools-extra (e.g. DLLVM_ENABLE_PROJECTS="clang;clang-tools-extra").

How do I stop clangd from indexing certain folders?

  # Note: This is a regexp, notice '.*' at the end of PathMatch string.
  PathMatch: /my/project/large/dir/.*
  # Disable slow background indexing of these files.
  Background: Skip

How do I make additional headers visible to clangd?

If you have some headers outside of the visibility of clangd, you can either include individual headers (-include=/headers/file.h) or add directories to the include path (-I=/other/headers). The easiest way to do that is through configuration file:

  Add: [-include=/headers/file.h, -I=/other/headers]

Why does clangd not return all references for a symbol?

One of the potential reasons is that clangd has not indexed all the files in your project. Please make sure all files are visible to clangd through the project setup and compile_commands.json.

If you are sure all files are indexed and can be accessed: clangd limits the number of returned results to prevent UI freezes by default. If you have more than a 1000 symbols and you would like to get through all of them, please pass --limit-references=0 to clangd invocation.

The same applies to the Remote Index Service but we are not respecting --limit-references=0 on the server side to prevent DDoS attacks.

How do I fix errors I get when opening headers outside of my project directory?

Clangd might fail to find suitable compile flags for headers outside of your project directory (e.g. third party dependencies installed elsewhere – for more details see here).

To work around this, you can instruct clangd to use your project’s compilation database for all files, not just files in the project directory.

In clangd 12 and later, this can be done by adding the following to your clangd config file:

  CompilationDatabase: <path>

where <path> is the directory containing the compilation database.

In older versions of clangd, this can be accomplished by passing the same path as a --compile-commands-dir=<path> command-line argument to clangd.

What can I do if clangd chooses the wrong source file to infer commands for a header?

A tool like CompDB can be used to post-process a compile_commands.json file to also contain entries for headers.

In the absence of entries for headers, clangd will use heuristics to choose a source file whose compile command to use when opening a header. The heuristics are currently based on filesystem paths and can sometimes choose the wrong source file, though improvements are planned.