Full Installation Guide

These are the steps necessary to get YCM working on a Unix OS and on Windows.

Note to Windows users: we assume that you are running the cmd.exe command prompt and that the needed executables are in the PATH environment variable. Do not just copy the shell commands. Replace ~ by %USERPROFILE% in them and use the right Vim home directory. It should be vimfiles by default instead of .vim.

See the FAQ if you have any issues.

Remember: YCM is a plugin with a compiled component. If you update YCM using Vundle and the ycm_core library APIs have changed (happens rarely), YCM will notify you to recompile it. You should then rerun the install process.

Please follow the instructions carefully. Read EVERY WORD.

1. Ensure that your version of Vim is at least the minimum version in the README and that it has support for Python 3 scripting.

   Inside Vim, type :version. Look at the first two to three lines of output; it should say Vi IMproved X.Y, where X.Y is the major version of vim. If your version is greater than 7.4, then you're all set. If your version is 7.4 then look below that where it says, Included patches: 1-Z, where Z will be some number. That number needs to be 1578 or higher.

   If your version of Vim is not recent enough, you may need to compile Vim from source (don't worry, it's easy).

   After you have made sure that you have Vim 7.4.1578+, type the following in Vim: :echo has('python') || has('python3'). The output should be 1. If it's 0, then get a version of Vim with Python support.

   NOTE: For all features, such as signature help, use Vim 8.1.1875 or later.

   On Windows, check also if your Vim architecture is 32 or 64-bit. This is critical because it must match the Python and the YCM libraries architectures. We recommend using a 64-bit Vim.

2. Install YCM with Vundle (or Pathogen, but Vundle is a better idea). With Vundle, this would mean adding a Plugin 'ycm-core/YouCompleteMe' line to your vimrc.

   If you don't install YCM with Vundle, make sure you have run git submodule update --init --recursive after checking out the YCM repository (Vundle will do this for you) to fetch YCM's dependencies.

3. Complete this step ONLY if you care about semantic completion support for C-family languages. Otherwise it's not necessary.

   YCM supports a clangd-based completer. You can download the latest version of clangd from llvm.org releases. Follow Step 4 to learn how to tell YCM where to find clangd binary. Please note that YCM is designed to work with clangd version 9.0.0 or higher.

   You can use the system clangd only if you are sure it is version 9.0.0 or higher, otherwise don't. Even if it is, we recommend using the official binaries from llvm.org if at all possible. Make sure you download the correct archive file for your OS.

   We STRONGLY recommend AGAINST use of the system clangd instead of the upstream compiled binaries. Random things may break. Save yourself the hassle and use the upstream pre-built clangd.

4. Compile the ycm_core library that YCM needs. This library is the C++ engine that YCM uses to get fast completions.

   You will need to have cmake installed in order to generate the required makefiles. Linux users can install cmake with their package manager (sudo apt-get install cmake for Ubuntu) whereas other users can download and install cmake from its project site. macOS users can also get it through Homebrew with brew install cmake.

   On a Unix OS, you need to make sure you have Python headers installed. On a Debian-like Linux distro, this would be sudo apt-get install python-dev python3-dev. On macOS they should already be present, but if they aren't get them through Homebrew with brew install python.

   On Windows, you need to download and install Python 3. Pick the version corresponding to your Vim architecture. You will also need Microsoft Visual C++ (MSVC) to build YCM. You can obtain it by installing Visual Studio Build Tools. MSVC 14 (Visual Studio 2015), 15 (2017) and 16 (2019) are officially supported.

   Here we'll assume you installed YCM with Vundle. That means that the top-level YCM directory is in ~/.vim/bundle/YouCompleteMe.

   We'll create a new folder where build files will be placed. Run the following:

   cd ~
   mkdir ycm_build
   cd ycm_build
   

   Now we need to generate the makefiles:

   cmake -G "<generator>" . ~/.vim/bundle/YouCompleteMe/third_party/ycmd/cpp
   

   where <generator> is Unix Makefiles on Unix systems and one of the following Visual Studio generators on Windows:

   • Visual Studio 14 Win64
   • Visual Studio 15 Win64
   • Visual Studio 16

   For MSVC 16 add -A x64 for the 64-bit install and -A Win32 for the 32-bit install. Remove the Win64 part in these generators if your Vim architecture is 32-bit.

   For those who want to use the system version of boost, you would pass -DUSE_SYSTEM_BOOST=ON to cmake. This may be necessary on some systems where the bundled version of boost doesn't compile out of the box.

   NOTE: We STRONGLY recommend AGAINST use of the system boost instead of the bundled version of boost. Random things may break. Save yourself the hassle and use the bundled version of boost.

   Now that configuration files have been generated, compile the libraries using this command:

   cmake --build . --target ycm_core --config Release
   

   The --config Release part is specific to Windows and will be ignored on a Unix OS.

   If you DO care about semantic support for C-family languages, and want to use clangd-based completer then you need to add following line to your vimrc:

   let g:ycm_clangd_binary_path = "/path/to/clangd"

   You need to change /path/to/clangd with the path of binary you downloaded in step 3.

5. Install watchdog library

   The watchdog dependency is located in YouCompleteMe/third_party/ycmd/third_party/watchdog_deps/watchdog/.

   1. For users with setuptools available

      Go to the watchdog directory, remove build/lib3 and run python setup.py build --build-base=build/3 --build-lib=build/lib3. This is the recommended option, especially on macOS.

   2. Install watchdog when setuptools isn't available

      Go to the watchdog directory, remove the build/lib3 directory and them copy the entire src/watchdog into build/lib3.

      On macOS this means that watchdog won't be able to use the faster fsevents API and will fallback to kqueue.

6. This step is optional.

   Build the regex module for improved Unicode support and better performance with regular expressions. The procedure is similar to compiling the ycm_core library:

   cd ~
   mkdir regex_build
   cd regex_build
   cmake -G "<generator>" . ~/.vim/bundle/YouCompleteMe/third_party/ycmd/third_party/cregex
   cmake --build . --target _regex --config Release
   

   where <generator> is the same generator used in the previous step.

7. Set up support for additional languages, as desired:

   • C# support: install Mono on non-Windows platforms. Navigate to YouCompleteMe/third_party/ycmd/third_party/omnisharp-roslyn. Download an Omnisharp-Roslyn release archive and extract the archive to YouCompleteMe/third_party/ycmd/third_party/omnisharp-roslyn.

     On Windows, be sure that the build utility msbuild is in your PATH.

   • Go support: install Go and add it to your path. Go to the root directory of your YCM installation and run the following command:

     GO111MODULE=on \
     GOPATH=$PWD/third_party/ycmd/third_party/go \
     GOBIN=$PWD/third_party/ycmd/third_party/go/bin \
     go get golang.org/x/tools/[email protected]
     

   • JavaScript and TypeScript support: install Node.js and npm, navigate to YouCompleteMe/third_party/ycmd and run npm install -g --prefix third_party/tsserver typescript.

   • Rust support: install rustup. Export RUSTUP_HOME environment variable and point it to an empty temporary directory. Run the following commands:

     rustup toolchain install nightly
     rustup default nightly
     rustup component add rls rust-analysis rust-src
     

     Ensure that YouCompleteMe/third_party/ycmd/third_party/rls directory exists and is empty. Go into the temporary directory and then into toolchains/<toolchain>. Finally, move everything from that directory to YouCompleteMe/third_party/ycmd/third_party/rls.

   • Java support: install JDK8 (version 8 required). Download a binary release of eclipse.jdt.ls and extract it to YouCompleteMe/third_party/ycmd/third_party/eclipse.jdt.ls/target/repository. Note: this approach is not recommended for most users and is supported only for advanced users and developers of YCM on a best-efforts basis. Please use install.py to enable java support.

That's it. You're done. Refer to the User Guide section on how to use YCM. Don't forget that if you want the C-family semantic completion engine to work, you will need to provide the compilation flags for your project to YCM. It's all in the User Guide.

YCM comes with sane defaults for its options, but you still may want to take a look at what's available for configuration. There are a few interesting options that are conservatively turned off by default that you may want to turn on.