# Neovim > - **IMPORTANT**: Before upgrading to a new version, **always check for [breaking changes](https://neovim.io/doc/user/news.html#news-breaking).** --- - **IMPORTANT**: Before upgrading to a new version, **always check for [breaking changes](https://neovim.io/doc/user/news.html#news-breaking).** ## Quick start 1. Install [build prerequisites](#build-prerequisites) on your system 2. `git clone https://github.com/neovim/neovim` 3. `cd neovim` - If you want the **stable release**, also run `git checkout stable`. 4. `make CMAKE_BUILD_TYPE=RelWithDebInfo` - If you want to install to a custom location, set `CMAKE_INSTALL_PREFIX`. See also [INSTALL.md](./INSTALL.md#install-from-source). - On BSD, use `gmake` instead of `make`. - To build on Windows, see the [Building on Windows](#building-on-windows) section. _MSVC (Visual Studio) is recommended._ 5. `sudo make install` - Default install location is `/usr/local` - On Debian/Ubuntu, instead of `sudo make install`, you can try `cd build && cpack -G DEB && sudo dpkg -i nvim-linux-.deb` (with `` either `x86_64` or `arm64`) to build DEB-package and install it. This helps ensure clean removal of installed files. Note: This is an unsupported, "best-effort" feature of the Nvim build. **Notes**: - From the repository's root directory, running `make` will download and build all the needed dependencies and put the `nvim` executable in `build/bin`. - Third-party dependencies (libuv, LuaJIT, etc.) are downloaded automatically to `.deps/`. See the [FAQ](https://neovim.io/doc/user/faq.html#faq-build) if you have issues. - After building, you can run the `nvim` executable without installing it by running `VIMRUNTIME=runtime ./build/bin/nvim`. - If you plan to develop Neovim, install [Ninja](https://ninja-build.org/) for faster builds. It will automatically be used. - Install [ccache](https://ccache.dev/) for faster rebuilds of Neovim. It's used by default. To disable it, use `CCACHE_DISABLE=true make`. ## Running tests See [test/README.md](https://github.com/neovim/neovim/blob/master/test/README.md). ## Building First make sure you installed the [build prerequisites](#build-prerequisites). Now that you have the dependencies, you can try other build targets explained below. The _build type_ determines the level of used compiler optimizations and debug information: - `Release`: Full compiler optimizations and no debug information. Expect the best performance from this build type. Often used by package maintainers. - `Debug`: Full debug information; few optimizations. Use this for development to get meaningful output from debuggers like GDB or LLDB. This is the default if `CMAKE_BUILD_TYPE` is not specified. - `RelWithDebInfo` ("Release With Debug Info"): Enables many optimizations and adds enough debug info so that when Neovim ever crashes, you can still get a backtrace. So, for a release build, just use: ``` make CMAKE_BUILD_TYPE=Release ``` (Do not add a `-j` flag if `ninja` is installed! The build will be in parallel automatically.) Afterwards, the `nvim` executable can be found in `build/bin`. To verify the build type after compilation, run: ```sh ./build/bin/nvim --version | grep ^Build ``` To install the executable to a certain location, use: ``` make CMAKE_INSTALL_PREFIX=$HOME/local/nvim install ``` CMake, our main build system, caches a lot of things in `build/CMakeCache.txt`. If you ever want to change `CMAKE_BUILD_TYPE` or `CMAKE_INSTALL_PREFIX`, run `rm -rf build` first. This is also required when rebuilding after a Git commit adds or removes files (including from `runtime`) — when in doubt, run `make distclean` (which is basically a shortcut for `rm -rf build .deps`). By default (`USE_BUNDLED=1`), Neovim downloads and statically links its needed dependencies. In order to be able to use a debugger on these libraries, you might want to compile them with debug information as well: ``` make distclean make deps ``` ## Building on Windows ### Windows / MSVC **MSVC (Visual Studio) is the recommended way to build on Windows.** These steps were confirmed as of 2023. 1. Install [Visual Studio](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community) (2017 or later) with the _Desktop development with C++_ workload. - On 32-bit Windows, you will need [this workaround](https://developercommunity.visualstudio.com/content/problem/212989/ninja-binary-format.html). 2. Open the Neovim project folder. - Visual Studio should detect the cmake files and automatically start building... 3. Choose the `nvim.exe (bin\nvim.exe)` target and hit F5. - If the build fails, it may be because Visual Studio started the build with `x64-{Debug,Release}` before you switched the configuration to `x86-Release`. - Right-click _CMakeLists.txt → Delete Cache_. - Right-click _CMakeLists.txt → Generate Cache_. - If you see an "access violation" from `ntdll`, you can ignore it and continue. 4. If you see an error like `uv.dll not found`, try the `nvim.exe (Install)` target. Then switch back to `nvim.exe (bin\nvim.exe)`. ### Windows / MSVC PowerShell To build from the command line (i.e. invoke the `cmake` commands yourself), 1. Ensure you have the Visual Studio environment variables, using any of the following: - Using the [Visual Studio Developer Command Prompt or Visual Studio Developer PowerShell](https://learn.microsoft.com/en-us/visualstudio/ide/reference/command-prompt-powershell?view=vs-2022) - Invoking `Import-VisualStudioVars` in PowerShell from [this PowerShell module](https://github.com/Pscx/Pscx) - Invoking `VsDevCmd.bat` in Command Prompt ``` VsDevCmd.bat -arch=x64 ``` This is to make sure that `luarocks` finds the Visual Studio installation, and doesn't fall back to MinGW with errors like: ``` 'mingw32-gcc' is not recognized as an internal or external command ``` 2. From the "Developer PowerShell" or "Developer Command Prompt": ``` cmake -S cmake.deps -B .deps -G Ninja -D CMAKE_BUILD_TYPE=Release cmake --build .deps --config Release cmake -B build -G Ninja -D CMAKE_BUILD_TYPE=Release cmake --build build --config Release ``` - Omit `--config Release` if you want a debug build. - Omit `-G Ninja` to use the "Visual Studio" generator. ### Windows / CLion 1. Install [CLion](https://www.jetbrains.com/clion/). 2. Open the Neovim project in CLion. 3. Select _Build → Build All in 'Release'_. ### Windows / Cygwin Since https://github.com/neovim/neovim/pull/36417 , building on Cygwin may be as easy as: make && make install If that fails, an alternative is: 1. Install all dependencies the normal way. - The `cygport` repo contains Cygport files (e.g. `APKBUILD`, `PKGBUILD`) 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 and consistent way. - https://github.com/cascent/neovim-cygwin was built on Cygwin 2.9.0. Newer `libuv` should require slightly less patching. Some SSP stuff changed in Cygwin 2.10.0, so that might change things too when building Neovim. 2. Build without "bundled" dependencies (except treesitter parsers). ``` cmake -S cmake.deps -B .deps -G Ninja -D CMAKE_BUILD_TYPE=RelWithDebInfo -DUSE_BUNDLED=OFF -DUSE_BUNDLED_TS=ON cmake --build .deps cmake -B build -G Ninja -D CMAKE_BUILD_TYPE=RelWithDebInfo cmake --build build ``` ### Windows / MSYS2 / MinGW 1. From the MSYS2 shell, install these packages: ``` pacman -S \ mingw-w64-ucrt-x86_64-gcc \ mingw-w64-x86_64-{cmake,make,ninja,diffutils} ``` 2. From the Windows Command Prompt (`cmd.exe`), set up the `PATH` and build. ```cmd set PATH=c:\msys64\ucrt64\bin;c:\msys64\usr\bin;%PATH% ``` 3. You have two options: - Build using `cmake` and `Ninja` generator: ```cmd cmake -S cmake.deps -B .deps -G Ninja -D CMAKE_BUILD_TYPE=RelWithDebInfo cmake --build .deps cmake -B build -G Ninja -D CMAKE_BUILD_TYPE=RelWithDebInfo cmake --build build ``` If you cannot install neovim with `ninja install` due to permission restriction, you can install neovim in a directory you have write access to. ```cmd cmake -S cmake.deps -B .deps -G Ninja -D CMAKE_BUILD_TYPE=RelWithDebInfo cmake --build .deps cmake -B build -G Ninja -D CMAKE_INSTALL_PREFIX=C:\nvim -D CMAKE_BUILD_TYPE=RelWithDebInfo cmake --build build ``` - Or, alternatively, you can use `mingw32-make`: ```cmd mingw32-make deps mingw32-make CMAKE_BUILD_TYPE=RelWithDebInfo :: Or you can do the previous command specifying a custom prefix :: (Default is C:\Program Files (x86)\nvim) :: mingw32-make CMAKE_BUILD_TYPE=RelWithDebInfo CMAKE_INSTALL_PREFIX=C:\nvim mingw32-make install ``` ### Windows WSL Build Ubuntu/Debian linux binary on [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) (Windows Subsystem for Linux). ```bash # Install build prerequisites sudo apt-get install ninja-build gettext cmake build-essential # Build the linux binary in WSL make CMAKE_BUILD_TYPE=RelWithDebInfo # Install the linux binary in WSL (with `` either `x86_64` or `arm64`) cd build && cpack -G DEB && sudo dpkg -i nvim-linux-.deb # Verify the installation nvim --version && which nvim # should be debug build in /usr/bin/nvim ``` **Note**: If you encounter linker errors or segfaults during the build, Windows libraries in your PATH may be interfering. Use a clean PATH to avoid conflicts: ```bash PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" make CMAKE_BUILD_TYPE=RelWithDebInfo ``` ## Localization ### Localization build Translations are turned off by default. Enable by building Nvim with the CMake flag `ENABLE_TRANSLATIONS=ON`. Doing this will create `.mo` files in `build/src/nvim/po`. Example: ``` make CMAKE_EXTRA_FLAGS="-DENABLE_TRANSLATIONS=ON" ``` * If you see `msgfmt: command not found`, you need to install [`gettext`](http://en.wikipedia.org/wiki/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: ``` cmake --build build --target check-po-de cmake --build build --target check-po-pt_BR ``` - `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: ``` cmake --build build --target update-po-$LANG ``` - **Note**: Run `src/nvim/po/cleanup.vim` after updating. ## Compiler options To see the chain of includes, use the `-H` option ([#918](https://github.com/neovim/neovim/issues/918)): ```sh 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. ## Custom Makefile You can customize the build process locally by creating a `local.mk`, 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 `local.mk` overrides the default make-target.** Here's a sample `local.mk` which adds a target to force a rebuild but *does not* override the default-target: ```make all: rebuild: rm -rf build make ``` ## Third-party dependencies Reference the [Debian package](https://packages.debian.org/sid/source/neovim) (or alternatively, the [Homebrew formula](https://github.com/Homebrew/homebrew-core/blob/master/Formula/n/neovim.rb)) for the precise list of dependencies/versions. To build the bundled dependencies using CMake: ```sh cmake -S cmake.deps -B .deps -G Ninja -D CMAKE_BUILD_TYPE=RelWithDebInfo cmake --build .deps ``` By default the libraries and headers are placed in `.deps/usr`. Now you can build Neovim: ```sh cmake -B build -G Ninja -D CMAKE_BUILD_TYPE=RelWithDebInfo cmake --build build ``` ### Build without "bundled" dependencies 1. Manually install the dependencies: - libuv libluv libutf8proc luajit lua-lpeg tree-sitter tree-sitter-c tree-sitter-lua tree-sitter-markdown tree-sitter-query tree-sitter-vim tree-sitter-vimdoc unibilium 2. Run CMake: ```sh cmake -B build -G Ninja -D CMAKE_BUILD_TYPE=RelWithDebInfo cmake --build build ``` If all the dependencies are not available in the package, you can use only some of the bundled dependencies as follows (example of using `ninja`): ```sh cmake -S cmake.deps -B .deps -G Ninja -D CMAKE_BUILD_TYPE=RelWithDebInfo -DUSE_BUNDLED=OFF -DUSE_BUNDLED_TS=ON cmake --build .deps cmake -B build -G Ninja -D CMAKE_BUILD_TYPE=RelWithDebInfo cmake --build build ``` 3. Run `make`, `ninja`, or whatever build tool you told CMake to generate. - Using `ninja` is strongly recommended. 4. If treesitter parsers are not bundled, they need to be available in a `parser/` runtime directory (e.g. `/usr/share/nvim/runtime/parser/`). ### Build offline On systems with old or missing libraries, *without* network access, you may want to build *with* bundled dependencies. This is supported as follows. 1. On a network-enabled machine, do either of the following, to get the dependency sources in `.deps` in a form that the build will work with: - Fetch https://github.com/neovim/deps/tree/master/src into `.deps/build/src/`. (https://github.com/neovim/deps/tree/master/src is an auto-updated, "cleaned up", snapshot of `.deps/build/src/`). - Run `make deps` to generate `.deps/`, then clean it up using [these commands](https://github.com/neovim/neovim/blob/1c12073db6c64eb365748f153f96be9b0fe61070/.github/workflows/build.yml#L67-L74). 2. Copy the prepared `.deps` to the isolated machine (without network access). 3. Build with `USE_EXISTING_SRC_DIR` enabled, on the isolated machine: ``` make deps DEPS_CMAKE_FLAGS=-DUSE_EXISTING_SRC_DIR=ON make ``` ### Build without unibilium Unibilium is the only dependency which is licensed under LGPLv3 (there are no GPLv3-only dependencies). This library is used for loading the terminfo database at runtime, and can be disabled if the internal definitions for common terminals are good enough. To avoid this dependency, build with support for loading custom terminfo at runtime, use ```sh make CMAKE_EXTRA_FLAGS="-DENABLE_UNIBILIUM=0" DEPS_CMAKE_FLAGS="-DUSE_BUNDLED_UNIBILIUM=0" ``` To confirm at runtime that unibilium was not included, check `has('terminfo') == 1`. ### Build with specific "bundled" dependencies Example of building with specific bundled and non-bundled dependencies: ``` make DEPS_CMAKE_FLAGS="-DUSE_BUNDLED=OFF -DUSE_BUNDLED_LUV=ON -DUSE_BUNDLED_TS=ON -DUSE_BUNDLED_LIBUV=ON" ``` ### Build static binary (Linux) 1. Use a linux distribution which uses musl C. We will use Alpine Linux but any distro with musl should work. (glibc does not support static linking) 2. Run make passing the `STATIC_BUILD` variable: `make CMAKE_EXTRA_FLAGS="-DSTATIC_BUILD=1"` In case you are not using Alpine Linux you can use a container to do the build the binary: ```sh podman run \ --rm \ -it \ -v "$PWD:/workdir" \ -w /workdir \ alpine:latest \ sh -c 'apk add build-base cmake coreutils curl gettext-tiny-dev git && make CMAKE_EXTRA_FLAGS="-DSTATIC_BUILD=1"' ``` The resulting binary in `build/bin/nvim` will have all the dependencies statically linked: ``` build/bin/nvim: ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV), statically linked, BuildID[sha1]=b93fa8e678d508ac0a76a2e3da20b119105f1b2d, with debug_info, not stripped ``` ## Build prerequisites General requirements (see [#1469](https://github.com/neovim/neovim/issues/1469#issuecomment-63058312)): - Clang or GCC version 4.9+ - CMake version 3.16+, built with TLS/SSL support - Optional: Get the latest CMake from https://cmake.org/download/ - Provides a shell script which works on most Linux systems. After running it, ensure the resulting `cmake` binary is in your $PATH so the the Nvim build will find it. Platform-specific requirements are listed below. ### Ubuntu / Debian ```sh sudo apt-get install ninja-build gettext cmake curl build-essential git ``` ### RHEL / Fedora ``` sudo dnf -y install ninja-build cmake gcc make gettext curl glibc-gconv-extra git ``` ### openSUSE ``` sudo zypper install ninja cmake gcc-c++ gettext-tools curl git ``` ### Arch Linux ``` sudo pacman -S base-devel cmake ninja curl git ``` ### Alpine Linux ``` apk add build-base cmake coreutils curl gettext-tiny-dev git ``` ### Void Linux ``` xbps-install base-devel cmake curl git ``` ### NixOS / Nix Starting from NixOS 18.03, the Neovim binary resides in the `neovim-unwrapped` Nix package (the `neovim` package being just a wrapper to setup runtime options like Ruby/Python support): ```sh cd path/to/neovim/src ``` Drop into `nix-shell` to pull in the Neovim dependencies: ``` nix-shell '' -A neovim-unwrapped ``` Configure and build: ```sh rm -rf build && cmakeConfigurePhase buildPhase ``` Tests are not available by default, because of some unfixed failures. You can enable them via adding this package in your overlay: ``` neovim-dev = (super.pkgs.neovim-unwrapped.override { doCheck=true; }).overrideAttrs(oa:{ cmakeBuildType="debug"; nativeBuildInputs = oa.nativeBuildInputs ++ [ self.pkgs.valgrind ]; shellHook = '' export NVIM_PYTHON_LOG_LEVEL=DEBUG export NVIM_LOG_FILE=/tmp/log export VALGRIND_LOG="$PWD/valgrind.log" ''; }); ``` and replacing `neovim-unwrapped` with `neovim-dev`: ``` nix-shell '' -A neovim-dev ``` A flake for Neovim is hosted at [nix-community/neovim-nightly-overlay](https://github.com/nix-community/neovim-nightly-overlay/), with 3 packages: - `neovim` to run the nightly - `neovim-debug` to run the package with debug symbols - `neovim-developer` to get all the tools to develop on `neovim` Thus you can run Neovim nightly with `nix run github:nix-community/neovim-nightly-overlay`. Similarly to develop on Neovim: `nix run github:nix-community/neovim-nightly-overlay#neovim-developer`. To use a specific version of Neovim, you can pass `--override-input neovim-src .` to use your current directory, or a specific SHA1 like `--override-input neovim-src github:neovim/neovim/89dc8f8f4e754e70cbe1624f030fb61bded41bc2`. ### Haiku Some deps can be pulled from haiku repos, the rest need "bundled" deps: cmake -DUSE_BUNDLED_LIBUV=OFF -DUSE_BUNDLED_UNIBILIUM=OFF -DUSE_BUNDLED_LUAJIT=OFF -B .deps ./cmake.deps make -C .deps ### FreeBSD ``` sudo pkg install cmake gmake sha wget gettext curl git ``` If you get an error regarding a `sha256sum` mismatch, where the actual SHA-256 hash is `e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`, then this is your issue (that's the `sha256sum` of an empty file). ### OpenBSD ```sh doas pkg_add gmake cmake curl gettext-tools git ``` Build can sometimes fail when using the top level `Makefile`, apparently due to some third-party component (see [#2445-comment](https://github.com/neovim/neovim/issues/2445#issuecomment-108124236)). The following instructions use CMake: ```sh mkdir .deps cd .deps cmake ../cmake.deps/ gmake cd .. mkdir build cd build cmake .. gmake ``` ### macOS #### macOS / Homebrew 1. Install Xcode Command Line Tools: `xcode-select --install` 2. Install [Homebrew](http://brew.sh) 3. Install Neovim build dependencies: ``` brew install ninja cmake gettext curl git ``` - **Note**: If you see Wget certificate errors (for older macOS versions less than 10.10): ```sh brew install curl-ca-bundle echo CA_CERTIFICATE=$(brew --prefix curl-ca-bundle)/share/ca-bundle.crt >> ~/.wgetrc ``` - **Note**: If you see `'stdio.h' file not found`, try the following: ``` open /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg ``` #### macOS / MacPorts 1. Install Xcode Command Line Tools: `xcode-select --install` 2. Install [MacPorts](http://www.macports.org) 3. Install Neovim build dependencies: ``` sudo port install ninja cmake gettext git ``` - **Note**: If you see Wget certificate errors (for older macOS versions less than 10.10): ```sh sudo port install curl-ca-bundle echo CA_CERTIFICATE=/opt/local/share/curl/curl-ca-bundle.crt >> ~/.wgetrc ``` - **Note**: If you see `'stdio.h' file not found`, try the following: ``` open /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg ``` #### Building for older macOS versions From a newer macOS version, to build for older macOS versions, you will have to set the macOS deployment target: ``` make CMAKE_BUILD_TYPE=Release MACOSX_DEPLOYMENT_TARGET=10.13 DEPS_CMAKE_FLAGS="-DCMAKE_CXX_COMPILER=$(xcrun -find c++)" ``` Note that the C++ compiler is explicitly set so that it can be found when the deployment target is set. --- Contributing to Neovim ====================== Getting started --------------- If you are new to the codebase, read [:help dev-quickstart](https://neovim.io/doc/user/dev_tools.html#dev-quickstart) to see how to run tests and start hacking on the codebase. If you want to help but don't know where to start, here are some low-risk/isolated tasks: - Try a [complexity:low] issue. - Fix bugs found by [Coverity](#coverity). - [Merge a Vim patch] (requires strong familiarity with Vim) - NOTE: read the above link before sending improvements to "runtime files" (anything in `runtime/`). - *Vimscript* files are (mostly) maintained by [Vim], not Nvim. - *Lua* files are maintained by *Nvim*. - Nvim's [filetype detection](https://github.com/neovim/neovim/blob/master/runtime/lua/vim/filetype.lua) behavior matches Vim, so changes to filetype detection should be submitted to [Vim] first. Reporting problems ------------------ - [Check the FAQ][wiki-faq]. - [Search existing issues][github-issues] (including closed!) - Update Neovim to the latest version to see if your problem persists. - Try to reproduce with `nvim --clean` ("factory defaults"). - If a specific configuration or plugin is necessary to recreate the problem, use the minimal template in `contrib/minimal.lua` with `nvim --clean -u contrib/minimal.lua` after making the necessary changes. - [Bisect](https://neovim.io/doc/user/starting.html#bisect) your config: disable plugins incrementally, to narrow down the cause of the issue. - [Bisect][git-bisect] Neovim's source code to find the cause of a regression, if you can. This is _extremely_ helpful. - When reporting a crash, [include a stacktrace](https://neovim.io/doc/user/dev_tools.html#dev-tools-backtrace). - Use [ASAN/UBSAN](#sanitizers-asan-and-ubsan) to get detailed errors for segfaults and undefined behavior. - Check the logs. `:edit $NVIM_LOG_FILE` - Include `cmake --system-information` for build-related issues. Developer guidelines -------------------- - Read [:help dev-quickstart](https://neovim.io/doc/user/dev_tools.html#dev-quickstart) to see how to run tests and start hacking on the codebase. - Read [:help dev](https://neovim.io/doc/user/dev.html#dev) and [:help dev-doc][dev-doc-guide] if you are working on Nvim core. - Read [:help dev-ui](https://neovim.io/doc/user/dev.html#dev-ui) if you are developing a UI. - Read [:help dev-api-client](https://neovim.io/doc/user/dev.html#dev-api-client) if you are developing an API client. - Install `ninja` for faster builds of Nvim. ```bash sudo apt-get install ninja-build make distclean make # Nvim build system uses ninja automatically, if available. ``` - Install `ccache` or `sccache` for faster rebuilds of Nvim. Nvim will use one of these automatically if it's found. To disable caching use: ```bash cmake -B build -D CACHE_PRG=OFF ``` Pull requests (PRs) --------------------- - Fork the repository first. - To avoid duplicate work, create a draft pull request. - Your PR must include [test coverage][run-tests]. - Avoid cosmetic changes to unrelated files in the same commit. - Use a [feature branch][git-feature-branch] instead of the master branch. - Use a _rebase workflow_ for all PRs. - After addressing review comments, it's fine to force-push. ### Merging to master For maintainers: when a PR is ready to merge to master, - prefer _Squash Merge_ for "single-commit PRs" (when the PR has only one meaningful commit). - prefer _Merge_ for "multi-commit PRs" (when the PR has multiple meaningful commits). ### Stages: Draft and Ready for review Pull requests have two stages: Draft and Ready for review. 1. [Create a Draft PR][pr-draft] while you are _not_ requesting feedback as you are still working on the PR. - You can skip this if your PR is ready for review. 2. [Change your PR to ready][pr-ready] when the PR is ready for review. - You can convert back to Draft at any time. Do __not__ add labels like `[RFC]` or `[WIP]` in the title to indicate the state of your PR: this just adds noise. Non-Draft PRs are assumed to be open for comments; if you want feedback from specific people, `@`-mention them in a comment. ### Commit messages Follow the [conventional commits guidelines][conventional_commits] to *make reviews easier* and to make the VCS/git logs more valuable (try `make lintcommit`). The structure of a commit message is: type(scope): subject Problem: ... Solution: ... - Commit message **subject** (you can **ignore this for "fixup" commits** or any commits you expect to be squashed): - Prefix with a [_type_](https://github.com/commitizen/conventional-commit-types/blob/master/index.json): - `build ci docs feat fix perf refactor revert test vim-patch` - Append an optional `(scope)` such as `(lsp)`, `(treesitter)`, `(float)`, … - Use the _imperative voice_: "Fix bug" rather than "Fixed bug" or "Fixes bug." - Keep it short (under 72 characters). - Commit message **body** (detail): - Concisely describe the Problem/Solution in the commit **body**. [Describing the problem](https://lamport.azurewebsites.net/pubs/state-the-problem.pdf) _independently of the solution_ often leads to a better understanding for you, reviewers, and future readers. ``` Problem: Solution: ``` - Indicate breaking API changes with "!" after the type, and a "BREAKING CHANGE" footer. Example: ``` refactor(provider)!: drop support for Python 2 BREAKING CHANGE: refactor to use Python 3 features since Python 2 is no longer supported. ``` ### Automated builds (CI) Each pull request must pass the automated builds on [Cirrus CI] and [GitHub Actions]. - CI builds are compiled with [`-Werror`][gcc-warnings], so compiler warnings will fail the build. - If any tests fail, the build will fail. See [test/README.md#running-tests][run-tests] to run tests locally. - CI runs [ASan] and other analyzers. - To run valgrind locally: `VALGRIND=1 make test` - To run ASan/UBSan locally: `CC=clang make CMAKE_FLAGS="-DENABLE_ASAN_UBSAN=ON"`. Note that MSVC requires Release or RelWithDebInfo build type to work properly. - The [lint](#lint) build checks that the code is formatted correctly and passes various linter checks. - CI for FreeBSD runs on [Cirrus CI]. - To see CI results faster in your PR, you can temporarily set `TEST_FILE` in [test.yml](https://github.com/neovim/neovim/blob/ad8e0cfc1dfd937c2577dc032e524c799a772693/.github/workflows/test.yml#L26). ### Coverity Coverity runs against the master build. To view the defects you must [request access](https://scan.coverity.com/projects/neovim-neovim) (Coverity does not have a "public" view), then you will be approved as soon as a maintainer sees the email. - Use this format for commit messages (where `{id}` is the CID (Coverity ID); ([example](https://github.com/neovim/neovim/pull/804))): ``` fix(coverity/{id}): {description} ``` - Search the Neovim commit history to find examples: ```bash git log --oneline --no-merges --grep coverity ``` ### Sanitizers (ASAN and UBSAN) ASAN/UBSAN can be used to detect memory errors and other common forms of undefined behavior at runtime in debug builds. - To build Neovim with sanitizers enabled, use ``` rm -rf build && CMAKE_EXTRA_FLAGS="-DCMAKE_C_COMPILER=clang -DENABLE_ASAN_UBSAN=1" make ``` - When running Neovim, use ``` ASAN_OPTIONS=log_path=/tmp/nvim_asan nvim args... ``` - If Neovim exits unexpectedly, check `/tmp/nvim_asan.{PID}` (or your preferred `log_path`) for log files with error messages. Coding ------ ### Lint You can run the linter locally by: ```bash make lint ``` ### Style - You can format files by using: ```bash make format # or formatc, formatlua ``` This will format changed Lua and C files with all appropriate flags set. - Style rules are (mostly) defined by `src/uncrustify.cfg` which tries to match the [style-guide]. To use the Nvim `gq` command with `uncrustify`: ```vim if !empty(findfile('src/uncrustify.cfg', ';')) setlocal formatprg=uncrustify\ -q\ -l\ C\ -c\ src/uncrustify.cfg\ --no-backup endif ``` - There is also `.clang-format` which has drifted from the [style-guide], but is available for reference. To use the Nvim `gq` command with `clang-format`: ```vim if !empty(findfile('.clang-format', ';')) setlocal formatprg=clang-format\ -style=file endif ``` ### Navigate - Set `blame.ignoreRevsFile` to ignore [noisy commits](https://github.com/neovim/neovim/commit/2d240024acbd68c2d3f82bc72cb12b1a4928c6bf) in git blame: ```bash git config blame.ignoreRevsFile .git-blame-ignore-revs ``` - Recommendation is to use **[clangd]**. Can use the maintained config in [nvim-lspconfig/clangd]. - Explore the source code [on the web](https://sourcegraph.com/github.com/neovim/neovim). ### Includes For managing includes in C files, use [include-what-you-use]. - [Install include-what-you-use][include-what-you-use-install] - To see which includes needs fixing use the cmake preset `iwyu`: ```bash cmake --preset iwyu cmake --build build ``` - There's also a make target that automatically fixes the suggestions from IWYU: ```bash make iwyu ``` See [#549][549] for more details. ### Lua runtime files The Lua [`runtime/lua/vim/_core/`](./runtime/lua/vim/_core/) modules are precompiled to bytecode, so changes won't be usable unless you (1) rebuild Nvim or (2) start Nvim with `--luamod-dev` and `$VIMRUNTIME`. For example try adding a function to `runtime/lua/vim/editor.lua`, then: ```bash VIMRUNTIME=./runtime ./build/bin/nvim --luamod-dev ``` Documentation ------------- Read [:help dev-doc][dev-doc-guide] to understand the expected documentation style and conventions. ### Generating :help Many `:help` docs are autogenerated from (C or Lua) docstrings. To generate the documentation run: ```bash make doc ``` To validate the documentation files, run: ```bash make lintdoc ``` If you need to modify or debug the documentation flow, these are the main files: - `./src/gen/gen_vimdoc.lua`: Main doc generator. Parses C and Lua files to render vimdoc files. - `./src/gen/luacats_parser.lua`: Documentation parser for Lua files. - `./src/gen/cdoc_parser.lua`: Documentation parser for C files. - `./src/gen/luacats_grammar.lua`: Lpeg grammar for LuaCATS - `./src/gen/cdoc_grammar.lua`: Lpeg grammar for C doc comments - `./src/gen/gen_eval_files.lua`: Generates documentation and Lua type files from metadata files: ``` runtime/lua/vim/* => runtime/doc/lua.txt runtime/lua/vim/* => runtime/doc/lua.txt runtime/lua/vim/lsp/ => runtime/doc/lsp.txt src/nvim/api/* => runtime/doc/api.txt src/nvim/eval.lua => runtime/doc/vimfn.txt src/nvim/options.lua => runtime/doc/options.txt ``` - `./scripts/lintdoc.lua`: Validation and linting of documentation files. ### Lua docstrings Use [LuaLS] annotations in Lua docstrings to annotate parameter types, return types, etc. See [:help dev-lua-doc][dev-lua-doc]. - The template for function documentation is: ```lua --- {Brief} --- --- {Long explanation} --- --- @param arg1 type {description} --- @param arg2 type {description} --- ... --- --- @return type {description} ``` - If possible, add type information (`table`, `string`, `number`, ...). Multiple valid types are separated by a bar (`string|table`). Indicate optional parameters via `type|nil`. - If a function in your Lua module should _not_ be documented, add `@nodoc`. - If the function is internal or otherwise non-public add `@private`. - Private functions usually should be underscore-prefixed (named "_foo", not "foo"). Prefixing with an underscore implies `@nodoc`. - Mark deprecated functions with `@deprecated`. Third-party dependencies ------------------------ To build Nvim using a different commit of a dependency change the appropriate URL in `cmake.deps/deps.txt`. For example, to use a different version of luajit replace the value in `LUAJIT_URL` with the wanted commit hash: ```bash LUAJIT_URL https://github.com/LuaJIT/LuaJIT/archive/.tar.gz ``` Set `DEPS_IGNORE_SHA` to `TRUE` in `cmake.deps/CMakeLists.txt` to skip hash check from cmake. Alternatively, you may point the URL as a local path where the repository is. This is convenient when bisecting a problem in a dependency with `git bisect`. This may require running `make distclean` between each build. Hash checking is always skipped in this case regardless of `DEPS_IGNORE_SHA`. ```bash LUAJIT_URL /home/user/luajit ``` Reviewing --------- Reviewing can be done on GitHub, but you may find it easier to do locally. Using [GitHub CLI][gh], you can create a new branch with the contents of a pull request, e.g. [#1820][1820]: ```bash gh pr checkout https://github.com/neovim/neovim/pull/1820 ``` Use [`git log -p master..FETCH_HEAD`][git-history-filtering] to list all commits in the feature branch which aren't in the `master` branch; `-p` shows each commit's diff. To show the whole surrounding function of a change as context, use the `-W` argument as well. [549]: https://github.com/neovim/neovim/issues/549 [1820]: https://github.com/neovim/neovim/pull/1820 [3174]: https://github.com/neovim/neovim/issues/3174 [ASan]: http://clang.llvm.org/docs/AddressSanitizer.html [Cirrus CI]: https://cirrus-ci.com/github/neovim/neovim [Clang report]: https://neovim.io/doc/reports/clang/ [GitHub Actions]: https://github.com/neovim/neovim/actions [Vim]: https://github.com/vim/vim [clangd]: https://clangd.llvm.org [Merge a Vim patch]: https://neovim.io/doc/user/dev_vimpatch.html [complexity:low]: https://github.com/neovim/neovim/issues?q=is%3Aopen+is%3Aissue+label%3Acomplexity%3Alow [conventional_commits]: https://www.conventionalcommits.org [dev-doc-guide]: https://neovim.io/doc/user/dev.html#dev-doc [dev-lua-doc]: https://neovim.io/doc/user/dev.html#dev-lua-doc [LuaLS]: https://luals.github.io/wiki/annotations/ [gcc-warnings]: https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html [gh]: https://cli.github.com/ [git-bisect]: http://git-scm.com/book/en/v2/Git-Tools-Debugging-with-Git [git-feature-branch]: https://www.atlassian.com/git/tutorials/comparing-workflows [git-history-filtering]: https://www.atlassian.com/git/tutorials/git-log/filtering-the-commit-history [github-issues]: https://github.com/neovim/neovim/issues [include-what-you-use-install]: https://github.com/include-what-you-use/include-what-you-use#how-to-install [include-what-you-use]: https://github.com/include-what-you-use/include-what-you-use#using-with-cmake [lua-language-server]: https://github.com/sumneko/lua-language-server/ [nvim-lspconfig/clangd]: https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#clangd [pr-draft]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request [pr-ready]: https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request [run-tests]: https://github.com/neovim/neovim/blob/master/runtime/doc/dev_test.txt [style-guide]: https://neovim.io/doc/user/dev_style.html#dev-style [wiki-faq]: https://neovim.io/doc/user/faq.html --- You can install Neovim from [download](#install-from-download), [package](#install-from-package), or [source](#install-from-source) in just a few seconds. --- - To start Neovim, run `nvim` (not `neovim`). - [Discover plugins](https://github.com/neovim/neovim/wiki/Related-projects#plugins). - Before upgrading to a new version, **check [Breaking Changes](https://neovim.io/doc/user/news.html#news-breaking).** - For config (vimrc) see [the FAQ](https://neovim.io/doc/user/faq.html#faq-general). --- Install from download ===================== Downloads are available on the [Releases](https://github.com/neovim/neovim/releases) page. * Latest [stable release](https://github.com/neovim/neovim/releases/latest) * [macOS x86_64](https://github.com/neovim/neovim/releases/latest/download/nvim-macos-x86_64.tar.gz) * [macOS arm64](https://github.com/neovim/neovim/releases/latest/download/nvim-macos-arm64.tar.gz) * [Linux x86_64](https://github.com/neovim/neovim/releases/latest/download/nvim-linux-x86_64.tar.gz) * [Linux arm64](https://github.com/neovim/neovim/releases/latest/download/nvim-linux-arm64.tar.gz) * [Windows](https://github.com/neovim/neovim/releases/latest/download/nvim-win64.msi) * Latest [development prerelease](https://github.com/neovim/neovim/releases/nightly) Install from package ==================== Packages are listed below. (You can also [build Neovim from source](#install-from-source).) ## Windows Windows 8+ is required. Windows 7 or older is not supported. ### [Winget](https://docs.microsoft.com/en-us/windows/package-manager/winget/) - **Release:** `winget install Neovim.Neovim` ### [Chocolatey](https://chocolatey.org) - **Latest Release:** `choco install neovim` (use -y for automatically skipping confirmation messages) - **Development (pre-release):** `choco install neovim --pre` ### [Scoop](https://scoop.sh/) ``` scoop bucket add main scoop install neovim ``` - **Release:** `scoop install neovim` Several Neovim GUIs are available from scoop (extras): [scoop.sh/#/apps?q=neovim](https://scoop.sh/#/apps?q=neovim) ### Pre-built archives 0. If you are missing `VCRUNTIME170.dll`, install the [Visual Studio C++ redistributable](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist) (choose x86_64 or x86 depending on your system). 1. Choose a package (**nvim-winXX.zip**) from the [releases page](https://github.com/neovim/neovim/releases). 2. Unzip the package. Any location is fine, administrator privileges are _not_ required. - `$VIMRUNTIME` will be set to that location automatically. 3. Run `nvim.exe` from a terminal. **Optional** steps: - Add the `bin` folder (e.g. `C:\Program Files\nvim\bin`) to your PATH. - This makes it easy to run `nvim` from anywhere. - If `:set spell` does not work, create the `%LOCALAPPDATA%/nvim-data/site/spell` folder. You can then copy your spell files over (for English, located [here](https://github.com/vim/vim/blob/master/runtime/spell/en.utf-8.spl) and [here](https://github.com/vim/vim/blob/master/runtime/spell/en.utf-8.sug)); - For Python plugins you need the `pynvim` module. Installation via uv (https://docs.astral.sh/uv/) is recommended; the `--upgrade` switch ensures installation of the latest version: ``` uv tool install --upgrade pynvim ``` - Run `:checkhealth` and read `:help provider-python` for more details. - **init.vim ("vimrc"):** If you already have Vim installed you can copy `%userprofile%\_vimrc` to `%userprofile%\AppData\Local\nvim\init.vim` to use your Vim config with Neovim. ## macOS / OS X ### Pre-built archives The [Releases](https://github.com/neovim/neovim/releases) page provides pre-built binaries for macOS 10.15+. For x86_64: curl -LO https://github.com/neovim/neovim/releases/download/nightly/nvim-macos-x86_64.tar.gz tar xzf nvim-macos-x86_64.tar.gz ./nvim-macos-x86_64/bin/nvim For arm64: curl -LO https://github.com/neovim/neovim/releases/download/nightly/nvim-macos-arm64.tar.gz tar xzf nvim-macos-arm64.tar.gz ./nvim-macos-arm64/bin/nvim ### [Homebrew](https://brew.sh) on macOS or Linux brew install neovim ### [MacPorts](https://www.macports.org/) sudo port selfupdate sudo port install neovim ## Linux ### Pre-built archives The [Releases](https://github.com/neovim/neovim/releases) page provides pre-built binaries for Linux systems. ```sh curl -LO https://github.com/neovim/neovim/releases/latest/download/nvim-linux-x86_64.tar.gz sudo rm -rf /opt/nvim-linux-x86_64 sudo tar -C /opt -xzf nvim-linux-x86_64.tar.gz ``` Then add this to your shell config (`~/.bashrc`, `~/.zshrc`, ...): export PATH="$PATH:/opt/nvim-linux-x86_64/bin" ### AppImage ("universal" Linux package) The [Releases](https://github.com/neovim/neovim/releases) page provides an [AppImage](https://appimage.org) that runs on most Linux systems. No installation is needed, just download `nvim-linux-x86_64.appimage` and run it. (It might not work if your Linux distribution is more than 4 years old.) The following instructions assume an `x86_64` architecture; on ARM Linux replace with `arm64`. curl -LO https://github.com/neovim/neovim/releases/latest/download/nvim-linux-x86_64.appimage chmod u+x nvim-linux-x86_64.appimage ./nvim-linux-x86_64.appimage To expose nvim globally: mkdir -p /opt/nvim mv nvim-linux-x86_64.appimage /opt/nvim/nvim And the following line to your shell config (`~/.bashrc`, `~/.zshrc`, ...): export PATH="$PATH:/opt/nvim/" If the `./nvim-linux-x86_64.appimage` command fails, try: ```sh ./nvim-linux-x86_64.appimage --appimage-extract ./squashfs-root/AppRun --version # Optional: exposing nvim globally. sudo mv squashfs-root / sudo ln -s /squashfs-root/AppRun /usr/bin/nvim nvim ``` ### Arch Linux Neovim can be installed from the community repository: sudo pacman -S neovim Alternatively, Neovim can be also installed using the PKGBUILD [`neovim-git`](https://aur.archlinux.org/packages/neovim-git), available on the [AUR](https://wiki.archlinux.org/index.php/Arch_User_Repository). Alternatively, Neovim Nightly builds can be also installed using the PKGBUILD [`neovim-nightly-bin`](https://aur.archlinux.org/packages/neovim-nightly-bin), available on the [AUR](https://wiki.archlinux.org/index.php/Arch_User_Repository). The Python module is available from the community repository: sudo pacman -S python-pynvim Ruby modules (currently only supported in `neovim-git`) are available from the AUR as [`ruby-neovim`](https://aur.archlinux.org/packages/ruby-neovim). ### CentOS 8 / RHEL 8 Neovim is available through [EPEL (Extra Packages for Enterprise Linux)](https://fedoraproject.org/wiki/EPEL) yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm yum install -y neovim python3-neovim ### Clear Linux OS Neovim is available through the [neovim bundle](https://github.com/clearlinux/clr-bundles/blob/master/bundles/neovim) sudo swupd bundle-add neovim Python (`:python`) support is available if the [python-basic bundle](https://github.com/clearlinux/clr-bundles/blob/master/bundles/python-basic) is installed. sudo swupd bundle-add python-basic ### Debian Neovim is in [Debian](https://packages.debian.org/search?keywords=neovim). sudo apt-get install neovim Python (`:python`) support is installable via the package manager on Debian unstable. sudo apt-get install python3-neovim ### Exherbo Linux Exhereses for scm and released versions are currently available in repository `::medvid`. Python client (with GTK+ GUI included) and Qt5 GUI are also available as suggestions: cave resolve app-editors/neovim --take dev-python/neovim-python --take app-editors/neovim-qt ### Fedora Neovim is in [Fedora](https://src.fedoraproject.org/rpms/neovim) starting with Fedora 25: sudo dnf install -y neovim python3-neovim You can also get nightly builds of git master from the [Copr automated build system](https://copr.fedoraproject.org/coprs/agriffis/neovim-nightly/): dnf copr enable agriffis/neovim-nightly dnf install -y neovim python3-neovim See the [blog post](https://arongriffis.com/2019-03-02-neovim-nightly-builds) for information on how these are built. ### Flatpak You can find Neovim on [Flathub](https://flathub.org/apps/details/io.neovim.nvim). Providing you have Flatpak [set up](https://flatpak.org/setup/): flatpak install flathub io.neovim.nvim flatpak run io.neovim.nvim You can add `/var/lib/flatpak/exports/bin` (or `~/.local/share/flatpak/exports/bin` if you used `--user`) to the `$PATH` and run it with `io.neovim.nvim`. Note that Flatpak'ed Neovim will look for `init.vim` in `~/.var/app/io.neovim.nvim/config/nvim` instead of `~/.config/nvim`. ### Gentoo Linux An ebuild is available in Gentoo's official portage repository: emerge -a app-editors/neovim ### GNU Guix Neovim can be installed with: guix install neovim ### GoboLinux Neovim can be installed with: sudo -H Compile NeoVim ### Nix / NixOS Neovim can be installed with: nix-env -iA nixpkgs.neovim Or alternatively, if you use flakes: nix profile install nixpkgs#neovim ### Mageia 7 urpmi neovim To install the Python modules: urpmi python3-pynvim ### makedeb Package Repository (MPR) Neovim is available inside the [MPR](https://mpr.makedeb.org/packages/neovim). You can install it with: git clone https://mpr.makedeb.org/neovim cd neovim/ makedeb -si ### OpenSUSE Neovim can be installed with: sudo zypper in neovim To install the Python modules: sudo zypper in python-neovim python3-neovim ### PLD Linux Neovim is in [PLD Linux](https://github.com/pld-linux/neovim): poldek -u neovim poldek -u python-neovim python3-neovim poldek -u python-neovim-gui python3-neovim-gui ### Slackware See [neovim on SlackBuilds](https://slackbuilds.org/apps/neovim/). ### Source Mage Neovim can be installed using the Sorcery package manager: cast neovim ### Solus Neovim can be installed using the default package manager in Solus (eopkg): sudo eopkg install neovim ### Snap Neovim nightly and stable are available on the [snap store](https://snapcraft.io/nvim). **Stable Builds** ```sh sudo snap install nvim --classic ``` **Nightly Builds** ```sh sudo snap install --edge nvim --classic ``` ### Ubuntu As in Debian, Neovim is in [Ubuntu](https://packages.ubuntu.com/search?keywords=neovim). sudo apt install neovim Python (`:python`) support seems to be automatically installed sudo apt install python3-neovim Neovim has been added to a "Personal Package Archive" (PPA). This allows you to install it with `apt-get`. Follow the links to the PPAs to see which versions of Ubuntu are currently available via the PPA. Choose **stable** or **unstable**: - [https://launchpad.net/~neovim-ppa/+archive/ubuntu/**stable**](https://launchpad.net/~neovim-ppa/+archive/ubuntu/stable) - [https://launchpad.net/~neovim-ppa/+archive/ubuntu/**unstable**](https://launchpad.net/~neovim-ppa/+archive/ubuntu/unstable) **Important:** The Neovim team does not maintain the PPA packages. For problems or questions about the PPA specifically contact https://launchpad.net/~neovim-ppa. To be able to use **add-apt-repository** you may need to install software-properties-common: sudo apt-get install software-properties-common If you're using an older version Ubuntu you must use: sudo apt-get install python-software-properties Run the following commands: sudo add-apt-repository ppa:neovim-ppa/stable sudo apt-get update sudo apt-get install neovim Prerequisites for the Python modules: sudo apt-get install python-dev python-pip python3-dev python3-pip If you're using an older version Ubuntu you must use: sudo apt-get install python-dev python-pip python3-dev sudo apt-get install python3-setuptools sudo easy_install3 pip ### Void-Linux Neovim can be installed using the xbps package manager sudo xbps-install -S neovim ### Alpine Linux Neovim can be installed using the apk package manager sudo apk add neovim ## BSD ### FreeBSD Neovim can be installed using [`pkg(8)`](https://www.freebsd.org/cgi/man.cgi?query=pkg&sektion=8&n=1): pkg install neovim or [from the ports tree](https://www.freshports.org/editors/neovim/): cd /usr/ports/editors/neovim/ && make install clean To install the pynvim Python modules using [`pkg(8)`](https://www.freebsd.org/cgi/man.cgi?query=pkg&sektion=8&n=1) run: pkg install py36-pynvim ### OpenBSD Neovim can be installed using [`pkg_add(1)`](https://man.openbsd.org/pkg_add): pkg_add neovim or [from the ports tree](https://cvsweb.openbsd.org/cgi-bin/cvsweb/ports/editors/neovim/): cd /usr/ports/editors/neovim/ && make install ## Android [Termux](https://github.com/termux/termux-app) offers a Neovim package. Install from source =================== If a package is not provided for your platform, you can build Neovim from source. See [BUILD.md](./BUILD.md) for details. If you have the [prerequisites](./BUILD.md#build-prerequisites) then building is easy: make CMAKE_BUILD_TYPE=Release sudo make install For Unix-like systems this installs Neovim to `/usr/local`, while for Windows to `C:\Program Files`. Note, however, that this can complicate uninstallation. The following example avoids this by isolating an installation under `$HOME/neovim`: rm -r build/ # clear the CMake cache make CMAKE_EXTRA_FLAGS="-DCMAKE_INSTALL_PREFIX=$HOME/neovim" make install export PATH="$HOME/neovim/bin:$PATH" ## Uninstall There is a CMake target to _uninstall_ after `make install`: ```sh sudo cmake --build build/ --target uninstall ``` Alternatively, just delete the `CMAKE_INSTALL_PREFIX` artifacts: ```sh sudo rm /usr/local/bin/nvim sudo rm -r /usr/local/share/nvim/ ``` ---

Neovim Documentation | Chat

[![Coverity Scan analysis](https://scan.coverity.com/projects/2227/badge.svg)](https://scan.coverity.com/projects/2227) [![Packages](https://repology.org/badge/tiny-repos/neovim.svg)](https://repology.org/metapackage/neovim) [![Debian CI](https://badges.debian.net/badges/debian/testing/neovim/version.svg)](https://buildd.debian.org/neovim) [![Downloads](https://img.shields.io/github/downloads/neovim/neovim/total.svg?maxAge=2592001)](https://github.com/neovim/neovim/releases/) Neovim is a project that seeks to aggressively refactor [Vim](https://www.vim.org/) in order to: - Simplify maintenance and encourage [contributions](CONTRIBUTING.md) - Split the work between multiple developers - Enable [advanced UIs] without modifications to the core - Maximize [extensibility](https://neovim.io/doc/user/api-ui-events.html#api-ui-events) See the [Introduction](https://github.com/neovim/neovim/wiki/Introduction) wiki page and [Roadmap] for more information. Features -------- - Modern [GUIs](https://github.com/neovim/neovim/wiki/Related-projects#gui) - [API access](https://github.com/neovim/neovim/wiki/Related-projects#api-clients) from any language including C/C++, C#, Clojure, D, Elixir, Go, Haskell, Java/Kotlin, JavaScript/Node.js, Julia, Lisp, Lua, Perl, Python, Racket, Ruby, Rust - Embedded, scriptable [terminal emulator](https://neovim.io/doc/user/terminal.html) - Asynchronous [job control](https://github.com/neovim/neovim/pull/2247) - [Shared data (shada)](https://github.com/neovim/neovim/pull/2506) among multiple editor instances - [XDG base directories](https://github.com/neovim/neovim/pull/3470) support - Compatible with most Vim plugins, including Ruby and Python plugins See [`:help nvim-features`][nvim-features] for the full list, and [`:help news`][nvim-news] for noteworthy changes in the latest version! Install from package -------------------- Pre-built packages for Windows, macOS, and Linux are found on the [Releases](https://github.com/neovim/neovim/releases/) page. [Managed packages] are in [Homebrew], [Debian], [Ubuntu], [Fedora], [Arch Linux], [Void Linux], [Gentoo], and more! Install from source ------------------- See [BUILD.md](./BUILD.md) and [supported platforms](https://neovim.io/doc/user/support.html#supported-platforms) for details. The build is CMake-based, but a Makefile is provided as a convenience. After installing the dependencies, run the following command. make CMAKE_BUILD_TYPE=RelWithDebInfo sudo make install To install to a non-default location: make CMAKE_BUILD_TYPE=RelWithDebInfo CMAKE_INSTALL_PREFIX=/full/path/ make install CMake hints for inspecting the build: - `cmake --build build --target help` lists all build targets. - `build/CMakeCache.txt` (or `cmake -LAH build/`) contains the resolved values of all CMake variables. - `build/compile_commands.json` shows the full compiler invocations for each translation unit. Transitioning from Vim -------------------- See [`:help nvim-from-vim`](https://neovim.io/doc/user/nvim.html#nvim-from-vim) for instructions. Project layout -------------- ├─ cmake/ CMake utils ├─ cmake.config/ CMake defines ├─ cmake.deps/ subproject to fetch and build dependencies (optional) ├─ runtime/ plugins and docs ├─ src/nvim/ application source code (see src/nvim/README.md) │ ├─ api/ API subsystem │ ├─ eval/ Vimscript subsystem │ ├─ event/ event-loop subsystem │ ├─ generators/ code generation (pre-compilation) │ ├─ lib/ generic data structures │ ├─ lua/ Lua subsystem │ ├─ msgpack_rpc/ RPC subsystem │ ├─ os/ low-level platform code │ └─ tui/ built-in UI └─ test/ tests (see test/README.md) License ------- Neovim contributions since [b17d96][license-commit] are licensed under the Apache 2.0 license, except for contributions copied from Vim (identified by the `vim-patch` token). See LICENSE for details. Vim is Charityware. You can use and copy it as much as you like, but you are encouraged to make a donation for needy children in Uganda. Please see the kcc section of the vim docs or visit the ICCF web site, available at these URLs: https://iccf-holland.org/ https://www.vim.org/iccf/ https://www.iccf.nl/ You can also sponsor the development of Vim. Vim sponsors can vote for features. The money goes to Uganda anyway. [license-commit]: https://github.com/neovim/neovim/commit/b17d9691a24099c9210289f16afb1a498a89d803 [nvim-features]: https://neovim.io/doc/user/vim_diff.html#nvim-features [nvim-news]: https://neovim.io/doc/user/news.html [Roadmap]: https://neovim.io/roadmap/ [advanced UIs]: https://github.com/neovim/neovim/wiki/Related-projects#gui [Managed packages]: ./INSTALL.md#install-from-package [Debian]: https://packages.debian.org/testing/neovim [Ubuntu]: https://packages.ubuntu.com/search?keywords=neovim [Fedora]: https://packages.fedoraproject.org/pkgs/neovim/neovim/ [Arch Linux]: https://www.archlinux.org/packages/?q=neovim [Void Linux]: https://voidlinux.org/packages/?arch=x86_64&q=neovim [Gentoo]: https://packages.gentoo.org/packages/app-editors/neovim [Homebrew]: https://formulae.brew.sh/formula/neovim