CLANGD(1)

📦
version 18.1.8 · 5 versions
, in debian trixie, ubuntu questing

👑 NAME 👑

clangd — the manual page for clangd 18, bestie. It's your editor's new BFF 💅

✨ DESCRIPTION ✨

🌈 OVERVIEW

clangd is a language server that hands out IDE-like features to editors. It's giving main character energy for your whole codebase 🦋

🫶 Real talk: you're supposed to use it through an editor plugin, not by running it directly yourself. Like, no cap.

Want more tea? Go read these:

Also, clangd will happily accept flags on the commandline, and it also reads them from the CLANGD_FLAGS environment variable. Two places, same vibe ✨

💻 USAGE

clangd [options]

🎀 OPTIONS

🔧 Generic Options

  • --help — shows you the available options (--help-hidden for even more, iykyk)
  • --help-list — shows you a list of available options (--help-list-hidden for more)
  • --version — shows you the version of this program. iconic.

🍓 clangd compilation flags options

  • --compile-commands-dir=<string> — point at a path to look for compile_commands.json. If that path is invalid, clangd will go looking in the current directory and the parent paths of each source file instead. it's flexible like that 💁
  • --query-driver=<string> — a comma separated list of globs that white-list gcc-compatible drivers that are safe to execute. Drivers matching any of these globs get used to extract system includes. e.g. /usr/bin/**/clang-*,/path/to/repo/**/g++-*
⚠️ Note the "safe to execute" part bestie, this one actually runs stuff. respect the white-list.

🌸 clangd feature options

  • --all-scopes-completion — if set to true, code completion will include index symbols that are not defined in the scopes (e.g. namespaces) visible from the code completion point. Such completions can insert scope qualifiers.
  • --background-index — index project code in the background and persist the index on disk. obsessed.
  • --background-index-priority=<value> — thread priority for building the background index. The effect of this flag is OS-specific.
    • =background — Minimum priority, runs on idle CPUs. May leave 'performance' cores unused.
    • =low — Reduced priority compared to interactive work.
    • =normal — Same priority as other clangd work.
  • --clang-tidy — enable clang-tidy diagnostics 🔥
  • --completion-style=<value> — granularity of code completion suggestions
    • =detailed — One completion item for each semantically distinct completion, with full type information
    • =bundled — Similar completion items (e.g. function overloads) are combined. Type information shown where possible
  • --fallback-style=<string> — the clang-format style to apply by default when no .clang-format file is found
  • --function-arg-placeholders — when disabled, completions contain only parentheses for function calls. When enabled, completions also contain placeholders for method parameters.
  • --header-insertion=<value> — add #include directives when accepting code completions
    • =iwyu — Include what you use. Insert the owning header for top-level symbols, unless the header is already directly included or the symbol is forward-declared
    • =never — Never insert #include directives as part of code completion
  • --header-insertion-decorators — prepend a circular dot or space before the completion label, depending on whether an include line will be inserted or not. cute little indicator ✨
  • --import-insertions — if header insertion is enabled, add #import directives when accepting code completions or fixing includes in Objective-C code
  • --limit-references=<int> — limit the number of references returned by clangd. 0 means no limit (default=1000)
  • --limit-results=<int> — limit the number of results returned by clangd. 0 means no limit (default=100)
  • --project-root=<string> — path to the project root. Requires remote-index-address to be set. (yes, that's a requirement, not a suggestion 💀)
  • --remote-index-address=<string> — address of the remote index server
  • --rename-file-limit=<int> — limit the number of files to be affected by symbol renaming. 0 means no limit (default=50)

🧚 clangd miscellaneous options

  • --check[=<string>] — parse one file in isolation instead of acting as a language server. Super useful to investigate/reproduce crashes or configuration problems. With --check=<filename>, it attempts to parse a particular file.
  • --enable-config — read user and project configuration from YAML files. Project config comes from a .clangd file in the project directory. User config comes from clangd/config.yaml in the following directories:
    • Windows: %USERPROFILE%\AppData\Local
    • Mac OS: ~/Library/Preferences/
    • Others: $XDG_CONFIG_HOME, usually ~/.config

Configuration is documented at https://clangd.llvm.org/config.html

  • -j <uint> — number of async workers used by clangd. The background index also uses this many workers. teamwork makes the dream work 🫶
  • --malloc-trim — release memory periodically via malloc_trim(3).
  • --pch-storage=<value> — storing PCHs in memory increases memory usages, but may improve performance
    • =disk — store PCHs on disk
    • =memory — store PCHs in memory

🦋 clangd protocol and logging options

  • --log=<value> — verbosity of log messages written to stderr
    • =error — Error messages only
    • =info — High level execution tracing
    • =verbose — Low level details
  • --offset-encoding=<value> — force the offsetEncoding used for character positions. This bypasses negotiation via client capabilities.
    • =utf-8 — Offsets are in UTF-8 bytes
    • =utf-16 — Offsets are in UTF-16 code units
    • =utf-32 — Offsets are in unicode codepoints
  • --path-mappings=<string> — translates between client paths (as seen by a remote editor) and server paths (where clangd sees files on disk). Comma separated list of '<client_path>=<server_path>' pairs, the first entry matching a given path is used. e.g. /home/project/incl=/opt/include,/home/project=/workarea/project
  • --pretty — pretty-print JSON output 💅✨

And that's the whole page bestie, you ate it up 👑

This one's from clangd 18, dated June 2025, and it lives in the CLANGD(1) section of the manual. Go forth and language-server, you absolute legend 🌈💖

📦 where this page comes from