Frequently Asked Questions (FAQ)
- How do I install clangd?
- How do I check the clangd version I am using?
- Can you give an example configuration file for clangd?
- How do I build clangd from sources?
- How do I stop clangd from indexing certain folders?
- How do I make additional headers visible to clangd?
- Why does clangd not return all references for a symbol?
- How do I fix errors I get when opening headers outside of my project directory?
- What can I do if clangd chooses the wrong source file to infer commands for a header?
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:
- Download the binaries from our GitHub repository:
- Compile from sources.
How do I check the clangd version I am using?
- Check the logs: clangd prints version on the first line. See your LSP client
documentation on where to find them: e.g. VSCode has logs in the output panel,
coc-clangd gives you the logs via
clangd --version. Note: the binary in your
$PATHmight not be the one used within the editor, checking logs is preferred.
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:
CompileFlags: # 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 Diagnostics: # Tweak Clang-Tidy checks. ClangTidy: Add: [performance*, modernize*, readability*] Remove: [modernize-use-trailing-return-type] CheckOptions: readability-identifier-naming.VariableCase: CamelCase --- # Use Remote Index Service for LLVM. If: # Note: This is a regexp, notice '.*' at the end of PathMatch string. PathMatch: /path/to/llvm/.* Index: External: Server: clangd-index.llvm.org:5900 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
instructions and make sure
How do I stop clangd from indexing certain folders?
If: # Note: This is a regexp, notice '.*' at the end of PathMatch string. PathMatch: /my/project/large/dir/.* Index: # 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:
CompileFlags: 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
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:
CompileFlags: CompilationDatabase: <path>
<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
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.