YouCompleteMe: a code-completion engine for Vim

Help, Advice, Support

Looking for help, advice, or support? Having problems getting YCM to work?

First carefully read the installation instructions for your OS. We recommend you use the supplied install.py - the "full" installation guide is for rare, advanced use cases and most users should use install.py.

If the server isn't starting and you're getting a "YouCompleteMe unavailable" error, check the [Troubleshooting][wiki-troubleshooting] guide.

Next, check the User Guide section on the semantic completer that you are using. For C/C++/Objective-C/Objective-C++/CUDA, you must read this section.

Finally, check the [FAQ][wiki-faq].

If, after reading the installation and user guides, and checking the FAQ, you're still having trouble, check the contacts section below for how to get in touch.

Please do NOT go to #vim on Freenode for support. Please contact the YouCompleteMe maintainers directly using the contact details below.

Vundle

Please note that the below instructions suggest using Vundle. Currently there are problems with Vundle, so here are some alternative instructions using Vim packages.

Contents

• Intro
• Installation
  • Requirements
  • macOS
  • Linux 64-bit
  • Windows
  • Full Installation Guide
• Quick Feature Summary
• User Guide
  • General Usage
  • Client-Server Architecture
  • Completion String Ranking
  • General Semantic Completion
  • Signature Help
  • Semantic Highlighting
  • Inlay Hints
  • C-family Semantic Completion
  • Java Semantic Completion
  • C# Semantic Completion
  • Python Semantic Completion
  • Rust Semantic Completion
  • Go Semantic Completion
  • JavaScript and TypeScript Semantic Completion
  • Semantic Completion for Other Languages
  • LSP Configuration
  • Writing New Semantic Completers
  • Diagnostic Display
    • Diagnostic Highlighting Groups
  • Symbol Search
  • Type/Call Hierarchy
• Commands
  • YcmCompleter subcommands
    • GoTo Commands
    • Semantic Information Commands
    • Refactoring Commands
    • Miscellaneous Commands
• Functions
• Autocommands
• Options
• FAQ
• Contributor Code of Conduct
• Contact
• License
• Sponsorship

Intro

YouCompleteMe is a fast, as-you-type, fuzzy-search code completion, comprehension and refactoring engine for [Vim][].

It has several completion engines built-in and supports any protocol-compliant Language Server, so can work with practically any language. YouCompleteMe contains:

• an identifier-based engine that works with every programming language,
• a powerful [clangd][]-based engine that provides native semantic code completion for C/C++/Objective-C/Objective-C++/CUDA (from now on referred to as "the C-family languages"),
• a [Jedi][]-based completion engine for Python 2 and 3,
• an [OmniSharp-Roslyn][]-based completion engine for C#,
• a [Gopls][]-based completion engine for Go,
• a [TSServer][]-based completion engine for JavaScript and TypeScript,
• a [rust-analyzer][]-based completion engine for Rust,
• a [jdt.ls][]-based completion engine for Java.
• a generic Language Server Protocol implementation for any language
• and an omnifunc-based completer that uses data from Vim's omnicomplete system to provide semantic completions for many other languages (Ruby, PHP, etc.).

Here's an explanation of what happened in the last GIF demo above.

First, realize that no keyboard shortcuts had to be pressed to get the list of completion candidates at any point in the demo. The user just types and the suggestions pop up by themselves. If the user doesn't find the completion suggestions relevant and/or just wants to type, they can do so; the completion engine will not interfere.

When the user sees a useful completion string being offered, they press the TAB key to accept it. This inserts the completion string. Repeated presses of the TAB key cycle through the offered completions.

If the offered completions are not relevant enough, the user can continue typing to further filter out unwanted completions.

A critical thing to notice is that the completion filtering is NOT based on the input being a string prefix of the completion (but that works too). The input needs to be a [subsequence][] match of a completion. This is a fancy way of saying that any input characters need to be present in a completion string in the order in which they appear in the input. So abc is a subsequence of xaybgc, but not of xbyxaxxc. After the filter, a complicated sorting system ranks the completion strings so that the most relevant ones rise to the top of the menu (so you usually need to press TAB just once).

All of the above works with any programming language because of the identifier-based completion engine. It collects all of the identifiers in the current file and other files you visit (and your tags files) and searches them when you type (identifiers are put into per-filetype groups).

The demo also shows the semantic engine in use. When the user presses ., -> or :: while typing in insert mode (for C++; different triggers are used for other languages), the semantic engine is triggered (it can also be triggered with a keyboard shortcut; see the rest of the docs).

The last thing that you can see in the demo is YCM's diagnostic display features (the little red X that shows up in the left gutter; inspired by [Syntastic][]) if you are editing a C-family file. As the completer engine compiles your file and detects warnings or errors, they will be presented in various ways. You don't need to save your file or press any keyboard shortcut to trigger this, it "just happens" in the background.

And that's not all...

YCM might be the only Vim completion engine with the correct Unicode support. Though we do assume UTF-8 everywhere.

YCM also provides semantic IDE-like features in a number of languages, including:

• displaying signature help (argument hints) when entering the arguments to a function call (Vim only)
• finding declarations, definitions, usages, etc. of identifiers, and an interactive symbol finder
• displaying type information for classes, variables, functions etc.,
• displaying documentation for methods, members, etc. in the preview window, or in a popup next to the cursor (Vim only)
• fixing common coding errors, like missing semi-colons, typos, etc.,
• semantic renaming of variables across files,
• formatting code,
• removing unused imports, sorting imports, etc.

For example, here's a demo of signature help:

Below we can see YCM being able to do a few things:

• Retrieve references across files
• Go to declaration/definition
• Expand auto in C++
• Fix some common errors, and provide refactorings, with FixIt
• Not shown in the GIF are GoToImplementation and GoToType for servers that support it.

And here's some documentation being shown in a hover popup, automatically and manually:

Features vary by file type, so make sure to check out the file type feature summary and the full list of completer subcommands to find out what's available for your favourite languages.

You'll also find that YCM has filepath completers (try typing ./ in a file) and a completer that integrates with [UltiSnips][].

Installation

Requirements

Runtime	Min Version	Recommended Version (full support)	Python
Vim	9.1.0016	9.1.0016	3.12
Neovim	0.5	Vim 9.1.0016	3.12

Supported Vim Versions

Our policy is to support the Vim version that's in the latest LTS of Ubuntu.

Vim must have a working Python 3 runtime.

For Neovim users, our policy is to require the latest released version. Currently, Neovim 0.5.0 is required. Please note that some features are not available in Neovim, and Neovim is not officially supported.

Supported Python runtime

YCM has two components: A server and a client. Both the server and client require Python 3.12 or later 3.x release.

For the Vim client, Vim must be, compiled with --enable-shared (or --enable-framework on macOS). You can check if this is working with :py3 import sys; print( sys.version). It should say something like 3.12.0 (...).

For Neovim, you must have a python 3.12 runtime and the Neovim python extensions. See Neovim's :help provider-python for how to set that up.

For the server, you must run the install.py script with a python 3.12 (or later) runtime. Anaconda etc. are not supported. YCM will remember the runtime you used to run install.py and will use that when launching the server, so if you usually use anaconda, then make sure to use the full path to a real cpython3, e.g. /usr/bin/python3 install.py --all etc.

Our policy is to support the python3 version that's available in the latest Ubuntu LTS (similar to our Vim version policy). We don't increase the Python runtime version without a reason, though. Typically, we do this when the current python version we're using goes out of support. At that time we will typically pick a version that will be supported for a number of years.

Supported Compilers

In order to provide the best possible performance and stability, ycmd has updated its code to C++17. This requires a version bump of the minimum supported compilers. The new requirements are:

Compiler	Current Min
GCC	8
Clang	7
MSVC	15.7 (VS 2017)

YCM requires CMake 3.13 or greater. If your CMake is too old, you may be able to simply pip install --user cmake to get a really new version.

Individual completer requirements

When enabling language support for a particular language, there may be runtime requirements, such as needing a very recent Java Development Kit for Java support. In general, YCM is not in control of the required versions for the downstream compilers, though we do our best to signal where we know them.

macOS

Quick start, installing all completers

• Install YCM plugin via [Vundle][]
• Install CMake, MacVim and Python 3; Note that the pre-installed macOS system Vim is not supported (due to it having broken Python integration).

$ brew install cmake python go nodejs

• Install mono from Mono Project (NOTE: on Intel Macs you can also brew install mono. On arm Macs, you may require Rosetta)

• For Java support you must install a JDK, one way to do this is with Homebrew:

$ brew install java
$ sudo ln -sfn $(brew --prefix java)/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk.jdk

• Pre-installed macOS system Vim does not support Python 3. So you need to install either a Vim that supports Python 3 OR [MacVim][] with [Homebrew][brew]:

• Option 1: Installing a Vim that supports Python 3

brew install vim

• Option 2: Installing [MacVim][]

brew install macvim

• Compile YCM.

• For Intel and arm64 Macs, the bundled libclang/clangd work:

  cd ~/.vim/bundle/YouCompleteMe python3 install.py --all

• If you have troubles with finding system frameworks or C++ standard library, try using the homebrew llvm:

  ``` brew install