Getting started

This page covers building Neovim from source and running its tests. The detailed user-facing build instructions live in BUILD.md and INSTALL.md at the repo root; this page is the developer path.

Prerequisites

You need a C compiler (gcc, clang, or MSVC), CMake ≥ 3.16, and a few other tools. The exact list per platform is in BUILD.md. Ninja is optional but strongly recommended (the build is parallel without -j when ninja is found). ccache or sccache are picked up automatically.

# Debian/Ubuntu
sudo apt install ninja-build gettext cmake unzip curl build-essential

# macOS
brew install ninja cmake gettext curl

# Arch
sudo pacman -S base-devel cmake unzip ninja curl

Bundled third-party dependencies (libuv, LuaJIT, libluv, lpeg, libvterm, unibilium, tree-sitter) are downloaded and built into .deps/ automatically by the top-level Makefile. You do not need to install them yourself.

Build

From the repo root:

make CMAKE_BUILD_TYPE=RelWithDebInfo

The binary lands in build/bin/nvim. You can run it directly:

VIMRUNTIME=runtime ./build/bin/nvim

The VIMRUNTIME=runtime is necessary so that the in-source build picks up the runtime/ directory rather than an installed one.

Build types you'll actually use:

CMAKE_BUILD_TYPE	When to use it
Debug	Default. Slow at runtime, full debug info, best for stepping in gdb/lldb.
RelWithDebInfo	Optimized but with debug info. The recommended developer build.
Release	Full optimizations, no debug info. What package maintainers ship.

Other useful invocations:

make distclean              # rm -rf build .deps
make deps                   # build only third-party deps
cmake --build build --target help   # list every build target
cmake -B build -LH          # show all CMake options
make iwyu                   # apply include-what-you-use suggestions

For debug-info on bundled deps (so you can step into libuv, etc.):

make distclean
make deps    # rebuild .deps/ with debug info

The build's compiler invocations are recorded in build/compile_commands.json. Point clangd at this file (the repo's .clangd already does so) and you get cross-file navigation in any LSP-aware editor, including Neovim itself.

Install

sudo make install

The default prefix is /usr/local. Override it with CMAKE_INSTALL_PREFIX:

make CMAKE_INSTALL_PREFIX=$HOME/local/nvim install

On Debian/Ubuntu, prefer building a .deb so uninstall is clean:

cd build && cpack -G DEB && sudo dpkg -i nvim-linux-*.deb

Run the tests

Neovim has two test suites, both written in Lua against the busted framework, plus C unit tests via FFI.

make functionaltest   # functional tests in test/functional/
make unittest         # unit tests in test/unit/
make test             # all of the above

To run a single test file:

TEST_FILE=test/functional/lua/diagnostic_spec.lua make functionaltest

To filter by name (busted --filter):

TEST_FILTER='vim.diagnostic.set' make functionaltest

There are also benchmark and old-style ("oldtest", from Vim) suites:

make benchmark
make oldtest

The full test docs are in test/README.md and runtime/doc/dev_test.txt.

Lint and format

make lint        # everything
make lintc       # C lint (clang-tidy + uncrustify check)
make lintlua     # luacheck + selene + stylua check
make lintdoc     # Validate runtime/doc/*.txt
make lintquery   # Validate tree-sitter query files

make format      # apply formatting in-place to changed files

The C style is defined by src/uncrustify.cfg and (loosely) by .clang-format. The Lua style is stylua against .stylua.toml.

CI runs all of these and additionally zizmor, include-what-you-use, and ASAN/UBSAN. Locally you can reproduce the sanitizer build with:

rm -rf build
CMAKE_EXTRA_FLAGS="-DCMAKE_C_COMPILER=clang -DENABLE_ASAN_UBSAN=1" make
ASAN_OPTIONS=log_path=/tmp/nvim_asan ./build/bin/nvim ...

Generate the docs

:help files in runtime/doc/ are partly authored by hand and partly generated from C/Lua docstrings:

make doc       # regenerate runtime/doc/api.txt, lua.txt, options.txt, ...
make lintdoc   # validate them

The generator is src/gen/gen_vimdoc.lua plus the cdoc_* and luacats_* parsers it depends on.

A first round trip

A reasonable smoke test that you have a working development build:

make CMAKE_BUILD_TYPE=Debug
./build/bin/nvim --version
VIMRUNTIME=runtime ./build/bin/nvim --clean +'echo "ok"' +q
TEST_FILE=test/functional/core/startup_spec.lua make functionaltest

If all three succeed, your toolchain is set up. Now read How to contribute for the rest of the developer workflow.