Building Neovim

Piping edited this page Aug 12, 2018 · 194 revisions

Quick start

  1. Verify that you have the build prerequisites installed.
  2. Clone neovim/neovim.
    • If you want the stable release: git checkout v0.3.1 (or the most-recent tag)
  3. Build Neovim by running make. (On BSD systems use gmake / GNU Make.)
    • Set CMAKE_INSTALL_PREFIX if you want to install to a custom location. See Installing Neovim.

Other notes:

  • Third-party dependencies (libuv, LuaJIT, etc.) are downloaded automatically to .deps/. See FAQ if you have issues.
  • To generate the Makefile without building: make cmake
  • If you plan to develop Neovim, install ninja for faster builds. It will be used automatically.

Now that you have the dependencies, you can try other build targets, explained below.

Running tests

See test/

Optimized builds

rm -r build
make clean

For developers and "edge" users, RelWithDebInfo is recommended over Release as the latter doesn't generate debug info.

To verify the build type after compilation, run ./build/bin/nvim --version | grep ^Build

Debug builds

nvim links statically some libraries, in order to be able to step into some of these functions, you might want to compile them with debug informations as well.

make distclean
VERBOSE=1 DEBUG=1 make deps


Localization build

A normal build will create .mo files in build/src/nvim/po.

  • If you see msgfmt: command not found, you need to install gettext. On most systems the package is just called gettext.

Localization check

To check the translations for $LANG, run make -C build check-po-$LANG. Examples:

make -C build check-po-de
make -C build check-po-pt_BR
  • Use ninja instead of make if applicable.
  • check-po-$LANG generates a detailed report in ./build/src/nvim/po/check-${LANG}.log. (The report is generated by nvim, not by msgfmt.)

Localization update

To update the src/nvim/po/$LANG.po file with the latest strings, run the following:

make -C build update-po-$LANG
  • Replace make with ninja if applicable.
  • Note: run src/nvim/po/cleanup.vim after updating.

Compiler options

To see the chain of includes, use the -H option (#918):

echo '#include "./src/nvim/buffer.h"' | \
> clang -I.deps/usr/include -Isrc -std=c99 -P -E -H - 2>&1 >/dev/null | \
> grep -v /usr/
  • grep -v /usr/ is used to filter out system header files
  • -save-temps can be added as well to see expanded macros or commented assembly

Xcode and MSVC project files

CMake has a -G option for exporting to multiple project file formats, such as Xcode and Visual Studio.

For example, to use Xcode's static analysis GUI (#167), you need to generate an Xcode project file from the Neovim makefile (where neovim/ is the top-level Neovim source code directory containing the main Makefile):

cmake -G Xcode neovim

then open the resulting project file in Xcode.

Custom Makefile

You can customize the build process locally by creating a, which is referenced at the top of the main Makefile. It's listed in .gitignore so it can be used across branches. A new target in overrides the default make-target.

Here's a sample which adds a target to force a rebuild but does not override the default-target:


	rm -rf build

Third-party dependencies

See #1588.

To build the bundled dependencies using CMake:

mkdir .deps ; cd .deps
cmake ../third-party

By default the libraries and headers are placed in .deps/usr. Now you can build Neovim:

mkdir build ; cd build
cmake ..

How to build without "bundled" dependencies

  1. Install all dependencies manually.
  2. Create directory build in the root of the repository.
  3. Switch to it and run cmake .. with all necessary options and environment. E.g.:
    CC=clang CFLAGS=" -O0 -g " cmake .. -DMIN_LOG_LEVEL=3 -DCMAKE_INSTALL_PREFIX=foo
  4. Run make.

About CMake

  • cmake -LAH prints all variable definitions.
  • build/CMakeCache.txt contains the resolved values of all variables used by CMake.
  • build/compile_commands.json shows the full compiler invocations for each translation unit.

Build prerequisites

General requirements (see #1469):

  • A recent version of Clang, or GCC version 4.4 and above
  • CMake version 2.8.7 and above, built with TLS/SSL support

Platform-specific requirements are listed below.

Ubuntu / Debian

sudo apt-get install ninja-build gettext libtool libtool-bin autoconf automake cmake g++ pkg-config unzip

Note: libtool-bin is only required for Ubuntu 16.04/Debian Jessie and newer.

CentOS / RHEL / Fedora

If you're using CentOS/RHEL 6 you need at least autoconf version 2.69 for compiling the libuv dependency. See

sudo yum -y install ninja-build libtool autoconf automake cmake gcc gcc-c++ make pkgconfig unzip


sudo zypper install ninja libtool autoconf automake cmake gcc-c++ gettext-tools

Arch Linux

sudo pacman -S base-devel cmake unzip ninja

Nix or NixOS

Starting from nixos 18.03, the neovim binary resides in the neovim-unwrapped nix package (theneovim` package being just a wrapper to setup runtime options like ruby/python support):

$ cd path/to/neovim/src
$ nix-shell '<nixpkgs>' -A neovim-unwrapped
$ cmakeConfigurePhase
build $ buildPhase

Running tests does not work out of the box yet. A PR submitted to improve lua support in nixpkgs includes a fix for running the functional tests at


sudo pkg install cmake gmake libtool sha automake pkgconf unzip wget gettext

If you get an error regarding a sha256sum mismatch, where the actual sha256sum is e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855, then this is your issue (that's the sha256sum of an empty file). Also, make sure you have wget installed. LuaRocks has bad interactions with cURL, at least under FreeBSD, and will die with a PANIC in LuaJIT when trying to install a rock.


doas pkg_add gmake cmake libtool unzip autoconf-2.69p2 automake-1.15p0

For older versions of OpenBSD than 6.1, the autoconf-2.69 and automake-1.15 ports may have different p suffixes.

The build sometimes fails when using the top level Makefile, apparently due to some third-party component #2445-comment. The following instructions use CMake

mkdir .deps
cd .deps
cmake ../third-party/
cd ..
mkdir build
cd build
cmake ..


  • Install Xcode and Homebrew or MacPorts
  • Install Xcode commandline tools xcode-select --install
  • Install other dependencies:
    • via MacPorts:
      sudo port install ninja libtool autoconf automake cmake pkgconfig gettext
    • via Homebrew:
      brew install ninja libtool automake cmake pkg-config gettext
  • If you see wget certificate errors (for macOS before version 10.10/Yosemite):
    • via MacPorts:
      sudo port install curl-ca-bundle
      echo CA_CERTIFICATE=/opt/local/share/curl/curl-ca-bundle.crt >> ~/.wgetrc
    • via Homebrew:
      brew install curl-ca-bundle
      echo CA_CERTIFICATE=$(brew --prefix curl-ca-bundle)/share/ca-bundle.crt >> ~/.wgetrc


Install all dependencies the normal way, then build neovim the normal way for a random CMake application (i.e. do not use the Makefile that automatically downloads and builds "bundled" dependencies)

The cygport repo contains cygport files (like APKBUILD, PKGBUILD, etc.) for all the dependencies not available in the cygwin distribution, and describes any special commands or arguments needed to build. the cygport definitions also try to describe the required dependencies for each one. unless custom commands are provided, cygport just calls autogen/cmake, make, make install, etc. in a clean, consistent way. was built on cygwin 2.9.0. Newer libuv should require slightly less patching and some ssp stuff changed in cygwin 2.10.0 so that might change things too when building neovim.

Windows / MSVC

  1. Install Visual Studio 2017 (includes CMake) with the Desktop development with C++ workload.
  2. Run makedeps.bat to build the dependencies. (No longer needed: deps are built automatically.)
  3. Start Visual Studio and open the Neovim project.
    • It should automatically detect and parse the project configuration. Otherwise right-click CMakeLists.txt and choose CMake → Generate.
  4. Select x86-Release configuration from the project settings menu and wait for CMake configuration to complete.
    • Note: It's also possible to build with the x64-Release configuration if cmake -G "Visual Studio 15 2017 Win64" is used to build the dependencies. However, the Debug configurations will not work because certain dependencies need to be linked with release version of the C runtime.
  5. Select CMake → Build All.

Windows / CLion

The steps for CLion are essentially the same as for Visual Studio, because the build logic is in CMake.

  1. Install CLion.
  2. Open the Neovim project in CLion.
  3. Select Build → nvim.exe.

Windows / MSYS2

From the MSYS2 shell install these packages

pacman -S \
    mingw-w64-x86_64-{gcc,libtool,cmake,make,perl,python2,pkg-config,unibilium} \

Now from the windows console (cmd.exe) setup the PATH and build

set PATH=c:\msys64\mingw64\bin;%PATH%
set CC=gcc

Build using the MinGW Makefiles generator

mkdir .deps
cd .deps
cmake  -G "MinGW Makefiles" ..\third-party\
cd ..
mkdir build
cd build
cmake -G "MinGW Makefiles" -DGPERF_PRG="C:\msys64\usr\bin\gperf.exe" ..

For 32bit builds adjust the package names and paths accordingly.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.