Neovim

Resources

Home

Official documentation

Package information

Wikipedia

GitHub

#neovim (webchat)

Open Hub

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.

Installation

USE flags

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

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

Data provided by the Gentoo Package Database · Last update: 2025-05-11 04:04 More information about USE flags

Emerge

root #emerge --ask app-editors/neovim

Note
After installation, it may be desirable to set the "vi" command to link to neovim. The system default text editor may also be set to use neovim.

Additional software

Plugins

Plugins extend the editor's functionality and are entirely optional. Many plugins for neovim may be found across the Internet, however much can be accomplished with "plain" neovim and sometimes being mindful not to get dragged down a configuration rabbit hole can help to stay productive (perhaps like Gentoo itself).

Note that vim plugins are usually compatible with neovim.

Plugins may be installed manually, though a plugin manager can make working with plugins much easier.

Plugin manager

Several plugin managers are available for neovim and they offer different functionality. Plugin managers often offer automatic plugin installation (as opposed to manually downloading plugins), automatic plugin updates, plugin configuration, etc.

Some examples of neovim plugin managers are vim-plug, pathogen, or lazy.nvim (not to be confused with LazyVim, which is a whole preconfigured neovim setup).

Configuration

Environment variables

Important environment variables include:

• NVIM_APPNAME - Allows starting neovim with an alternative configuration, for example for testing or if maintaining several separate neovim configurations is required. Run :help $NVIM_APPNAME in neovim for more information.
• VIMRUNTIME - Used to locate runtime files (documentation, syntax highlighting, etc.).
• VIMINIT - Ex commands to be executed at startup. Run :help VIMINIT in neovim for more information.

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

Files

Neovim honors XDG base directories. 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

The above configuration may alternatively be achieved with Neovim's init.lua:

FILE $XDG_CONFIG_HOME/nvim/init.lua

local options = {
    -- Sets the line number on the left-hand side.
    number = true,
    -- Sets the relative line number on the left-hand side.
    relativenumber = true,
    -- Sets the number of whitespace a \t char represents (hitting the tab key on your keyboard).
    tabstop = 4,
    -- Sets the number of whitespace considered as an indent.
    shiftwidth = 4,
    -- Replaces \t with whitespaces.
    expandtab = true
}

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

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.

Usage

Invocation

user $nvim --help

Usage:
  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

Options:
  --                    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.

Tutorial

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

user $nvim +Tutor

Removal

Unmerge

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

Troubleshooting

I'm trapped in neovim!

See also
As Vim and Neovim share the same basic commands, see the corresponding section in the Vim article on how to exit vi-like editors.

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

user $export TERM=screen-256color

user $screen

See: https://github.com/neovim/neovim/wiki/FAQ#home-or-some-other-special-key-doesnt-work

No syntax highlighting on Gentoo configuration files

  Note to editors

This section needs work, if anyone with more advanced knowledge of neovim or app-vim/gentoo-syntax could help. Perhaps the plugin could be installed "natively" with neovim rather than using lazy.nvim...

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.

Workaround

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

vim.opt.rtp:append('/usr/share/vim/vimfiles')

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.

Install gentoo-syntax with lazy.nvim

Installing the app-vim/gentoo-syntax package with portage will make the plugin available for vim, but not currently for neovim. It appears to be possible to install the gentoo-syntax vim plugin in neovim with the lazy.nvim plugin manager however. If using the lazy.nvim package manager, this may be an alternative for the previous workaround.

Create a file to install gentoo-syntax, just like installing any other plugin with lazy.nvim (the $XDG_CONFIG_HOME directory is often ~/.config/):

FILE $XDG_CONFIG_HOME/nvim/lua/plugins/gentoo.lua

return {
  {
    "https://github.com/gentoo/gentoo-syntax",
   },
}

Then run an installation or sync with lazy.nvim as usual.

Want to contribute

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

See also

• Knowledge Base:Edit a configuration file
• Text editor — a program to create and edit text files.
• Vi — a powerful "modal" text-based editor with a long history in the Unix(like) operating system.
• Vim — a text editor based on the vi text editor.
• Vim/Guide — explain basic usage for users new to vi-like text editors in general, and vim in particular.