From Gentoo Wiki
Jump to:navigation Jump to:search

Neovim is a hyperextensible Vim-based text editor.

See also
The Vim article provides general information on vi-like editors. See the Vim guide for an introductory tutorial on vi-like editor usage. See the text editor article for general information on installing and configuring text editors in Gentoo.


USE flags

USE flags for app-editors/neovim Vim-fork focused on extensibility and agility

nvimpager Install nvimpager symlink to macro
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)


root #emerge --ask app-editors/neovim

Additional software

Plugin manager

A plugin manager allows installation of plugins to Neovim editor to make it function according to user preference.

Vim plug

This is a plugin manager made both for Vim and Neovim. Here is the GitHub page: vim-plug. Read the GitHub page for any issues encountered.

Read more about it in


To install it for Neovim do the following:

user $sh -c 'curl -fLo "${XDG_DATA_HOME:-$HOME/.local/share}"/nvim/site/autoload/plug.vim --create-dirs \'

Or for flatpak:

user $curl -fLo ~/.var/app/io.neovim.nvim/data/nvim/site/autoload/plug.vim --create-dirs \

To configure you must read the vim-plug/wiki/tutorial

Here is a sample config

FILE $XDG_CONFIG_HOME/nvim/init.vim
call plug#begin()

Plug 'junegunn/vim-easy-align'

" Any valid git URL is allowed
Plug ''

" Multiple Plug commands can be written in a single line using | separators
Plug 'SirVer/ultisnips' | Plug 'honza/vim-snippets'

" On-demand loading
Plug 'scrooloose/nerdtree', { 'on':  'NERDTreeToggle' }
Plug 'tpope/vim-fireplace', { 'for': 'clojure' }

" Using a non-default branch
Plug 'rdnetto/YCM-Generator', { 'branch': 'stable' }

" Using a tagged release; wildcard allowed (requires git 1.9.2 or above)
Plug 'fatih/vim-go', { 'tag': '*' }

" Plugin options
Plug 'nsf/gocode', { 'tag': 'v.20150303', 'rtp': 'vim' }

" Plugin outside ~/.vim/plugged with post-update hook
Plug 'junegunn/fzf', { 'dir': '~/.fzf', 'do': './install --all' }

" Unmanaged plugin (manually installed and updated)
Plug '~/my-prototype-plugin'

call plug#end()
Vim Pathogen

Read more about Vim Pathogen over at


To install it, you can do

user $mkdir -p ~/.vim/autoload ~/.vim/bundle && \ curl -LSso ~/.vim/autoload/pathogen.vim

To learn more about configuration for Vim Pathogen, read their's

Here is a sample config given

FILE $XDG_CONFIG_HOME/nvim/init.vim
execute pathogen#infect()
syntax on
filetype plugin indent on

This is a super minimal config, that can get you starting.


Environment variables

Important environment variables include:

  • VIMRUNTIME - Used to locate runtime files (documentation, syntax highlighting, etc.).
  • VIMINIT - Ex commands to be executed at startup. Run :help VIMINIT

A full list of environment variables can be found under the environment section of man 1 nvim.


Neovim honors XDG base directories.[1] Therefore the configuration directories are defined by XDG_CONFIG_HOME (defaults to ~/.config) or XDG_CONFIG_DIRS (defaults to /etc/xdg) variables.

  • $XDG_CONFIG_HOME/nvim - User-local Neovim configuration directory
  • $XDG_CONFIG_HOME/nvim/init.vim - User-local Neovim configuration file
  • $XDG_CONFIG_HOME/nvim/init.lua - User-local Neovim Lua configuration file.
  • $XDG_CONFIG_DIRS/nvim/sysinit.vim - System-global Neovim configuration file

For example, customize Neovim for a specific user by editing the:

FILE $XDG_CONFIG_HOME/nvim/init.vim
set number
" sets the number on left-hand side
set relativenumber
" sets relative number on left-hand side
set tabstop=4
set shiftwidth=4
set expandtab
" sets the tab to be 4 spaces

You may alternatively achieve the same as above by using Neovim's init.lua:

FILE $XDG_CONFIG_HOME/nvim/init.lua
local options = {
    -- Sets the number on the left-hand side.
    number = true,
    -- Sets the relative number on the left-hand side.
    relativenumber = true,
    -- Sets the number of whitespace a \t char is worth (hitting tab key on your keyboard).
    tabstop = 4,
    -- Sets the number of whitespaces which is considered as an indent.
    shiftwidth = 4,
    -- Replaces \t with whitespaces.
    expandtab = true

-- Appends vim.opt to all of the options we defined above; using a loop.
for k, v in pairs (options) do
    vim.opt[k] = v

This particular example activates line numbers on the left-hand side of the editor, sets relative numbers, and changes the tab width.

For a full list of options, type

:help options

while in vim normal mode.



user $nvim --help
  nvim [options] [file ...]      Edit file(s)
  nvim [options] -t <tag>        Edit file where tag is defined
  nvim [options] -q [errorfile]  Edit file with first error

  --                    Only file names after this
  +                     Start at end of file
  --cmd <cmd>           Execute <cmd> before any config
  +<cmd>, -c <cmd>      Execute <cmd> after config and first file

  -b                    Binary mode
  -d                    Diff mode
  -e, -E                Ex mode
  -es, -Es              Silent (batch) mode
  -h, --help            Print this help message
  -i <shada>            Use this shada file
  -m                    Modifications (writing files) not allowed
  -M                    Modifications in text not allowed
  -n                    No swap file, use memory only
  -o[N]                 Open N windows (default: one per file)
  -O[N]                 Open N vertical windows (default: one per file)
  -p[N]                 Open N tab pages (default: one per file)
  -r, -L                List swap files
  -r <file>             Recover edit state for this file
  -R                    Read-only mode
  -S <session>          Source <session> after loading the first file
  -s <scriptin>         Read Normal mode commands from <scriptin>
  -u <config>           Use this config file
  -v, --version         Print version information
  -V[N][file]           Verbose [level][file]

  --api-info            Write msgpack-encoded API metadata to stdout
  --embed               Use stdin/stdout as a msgpack-rpc channel
  --headless            Don't start a user interface
  --listen <address>    Serve RPC API from this address
  --noplugin            Don't load plugins
  --startuptime <file>  Write startup timing messages to <file>

See ":help startup-options" for all options.


Neovim has a built-in tutorial. Learn basic nvim usage interactively with the +Tutor:

user $nvim +Tutor



root #emerge --ask --depclean --verbose app-editors/neovim


No colors when running through a terminal multiplexer such as screen or tmux

user $export TERM=screen-256color
user $screen


No syntax highlighting on Gentoo configuration files

Unfortunately, app-vim/gentoo-syntax has no native support for Neovim yet. Thus, Gentoo configuration files (e.g. most files under /etc/portage) don't have specialized syntax highlighting and the editor doesn't initialize the buffer for new Gentoo files (e.g. new ebuilds, new init scripts) with a skeleton.

Since Neovim is compatible with Vim configuration, the /usr/share/vim/vimfiles directory, where the system wide installed Vim plugins reside, can be added to the Neovim runtime path in $XDG_CONFIG_HOME/nvim/init.vim:

FILE $XDG_CONFIG_HOME/nvim/init.vim
set rtp+=/usr/share/vim/vimfiles

To do the same if using Lua configuration, edit $XDG_CONFIG_HOME/nvim/init.lua:

FILE $XDG_CONFIG_HOME/nvim/init.lua

If you're using Lazy as your plugin manager, the previous won't work since Lazy will reset the runtime path by default. You can instead do the following:

FILE $XDG_CONFIG_HOME/nvim/init.vim
require("lazy").setup({...}, {
  performance = {
    rtp = {
      paths = { "/usr/share/vim/vimfiles" }

However, this is just a workaround with the side effect that all other plugins which are installed for Vim system wide are now enabled in Neovim as well.

Want to contribute

Neovim is a community fork of Vim. Contribute here: Github: Neovim

See also


  1. XDG base directory specification support #3470 , GitHub. Retrieved on December 31, 2021