Neovim

This page only deals with major differences between Neovim and Vim. See Vim page for general Vim-related information.

References

• https://neovim.io/
• https://gitter.im/neovim/neovim

Dotfiles examples

• http://nerditya.com/code/guide-to-neovim/
• new — http://coderoncode.com/tools/2017/04/16/vim-the-perfect-ide.html
• new-2023 — https://github.com/AstroNvim/AstroNvim

Tools

• https://github.com/mhinz/neovim-remote

Replace vim --servername VIM, which Neovim doesn't support.

Install

✐	Last method used: Build on Debian, with neovim 0.5.1, following InstallNeovim.sh script.

❗	Avoid AppImage package. I had issue with bad runtimepath when using Session.vim file (vimprj). Prefer to build from source instead.

See the guide Installing Neovim.

On Ubuntu, we install from Neovim repository, tracking HEAD:

# sudo add-apt-repository ppa:neovim-ppa/unstable  # unstable has blinking cursor issues (see below)
sudo add-apt-repository ppa:neovim-ppa/stable
sudo apt-get update
sudo apt-get install neovim

Default ini files are located at ~/.config/nvim/init.vim. To import Vim settings (FAQ :help nvim-from-vim)

mkdir ~/.config
ln -s ~/.vim ~/.config/nvim
ln -s ~/.vimrc ~/.config/nvim/init.vim

Configure nvim as default vim alternative:

# The steps below might require the following configuration first (Ubuntu)
sudo update-alternatives --install /usr/bin/vi vi /usr/bin/nvim 60
sudo update-alternatives --install /usr/bin/vim vim /usr/bin/nvim 60
sudo update-alternatives --install /usr/bin/editor editor /usr/bin/nvim 60

sudo update-alternatives --config vi
sudo update-alternatives --config vim
sudo update-alternatives --config editor

Install Ruby gems for Ruby support:

sudo apt install ruby-dev
sudo gem install neovim
# If neovim still doesn't find neovim-ruby-host, 
# ... do /usr/local/bin/neovim-ruby-host --version to check all is fine
# ... typical fix: sudo apt install ruby-multi-json

Install Python package for Python support:

# Through Debian apt:
sudo apt-get install python-neovim
sudo apt-get install python3-neovim

# Or using pip
# OLD: sudo pip install neovim
sudo pip3 install --upgrade pynvim
sudo pip2 install --upgrade pynvim

Install npm support:

sudo npm install -g neovim

Install neovim-remote (nvr, support for --servername, required by plugin Vimtex):

sudo pip3 install neovim-remote

Fix clipboard timeout issue at startup:

vim /usr/local/share/nvim/runtime/autoload/provider/clipboard.vim
# +  elseif exists('$DISPLAY') && executable('xsel')
# -  elseif exists('$DISPLAY') && executable('xsel') && s:cmd_ok('xsel -o -b')

Build on debian

New method

• Check this page: https://gist.github.com/darcyparker/153124662b05c679c417 (installNeovim.sh).

# Remove python-pip because conflicting
sudo apt-get install -y \
  autoconf automake cmake g++ gettext libncurses5-dev libtool libtool-bin \
  libunibilium-dev libunibilium4 ninja-build pkg-config python3-pip software-properties-common unzip
sudo pip install setuptools
sudo pip install --upgrade pynvim
sudo pip3 install setuptools
sudo pip3 install --upgrade pynvim
sudo gem install neovim
sudo npm install -g neovim
make CMAKE_BUILD_TYPE=RelWithDebInfo CMAKE_EXTRA_FLAGS="-DCMAKE_INSTALL_PREFIX=/usr/local/"
sudo make install

# Install alternatives to /usr/local/bin
sudo update-alternatives --install /usr/bin/vi vi /usr/local/bin/nvim 60
sudo update-alternatives --install /usr/bin/vim vim /usr/local/bin/nvim 60
sudo update-alternatives --install /usr/bin/editor editor /usr/local/bin/nvim 60

sudo update-alternatives --config vi
sudo update-alternatives --config vim
sudo update-alternatives --config editor

• Then start neovim with nvim, and use command :checkhealth to check install.

Old method

• Download latest git and debian folder [1]:

git clone https://github.com/neovim/neovim.git
wget http://http.debian.net/debian/pool/main/n/neovim/neovim_0.2.0-3.debian.tar.xz
cd neovim
tar xvf ../neovim_0.2.0-3.debian.tar.xz

• Patch debian folder. First disable the tests:

--- a/debian/rules
+++ b/debian/rules
@@ -52,5 +52,3 @@ debian/fakehome:
 override_dh_auto_test-indep:
 
 override_dh_auto_test-arch: debian/passwd debian/fakehome
-       mv -f test/functional/ex_cmds/global_spec.lua debian/
-       env "HOME=$(CURDIR)/debian/fakehome" LD_PRELOAD=libnss_wrapper.so "NSS_WRAPPER_PASSWD=$(CURDIR)/debian/passwd" "NSS_WRAPPER_GROUP=$(CURDIR)/debian/group" make $(UNITTEST) $(FUNCTIONALTEST) oldtest VERBOSE=1 USE_BUNDLED_DEPS=OFF

• Then disable --fail-missing:

--- a/debian/rules
+++ b/debian/rules
 override_dh_install:
-       dh_install --fail-missing
+       dh_install

This is a temporary fix for error:

dh_install --fail-missing
dh_install: usr/share/applications/nvim.desktop exists in debian/tmp but is not installed to anywhere
dh_install: usr/share/pixmaps/nvim.png exists in debian/tmp but is not installed to anywhere
dh_install: missing files, aborting

• Install some dependencies (should use the apt )

# sudo apt-get build-dep neovim/stretch
# OR sudo apt-get build-dep neovim/sid
sudo apt install debhelper=10.2.5
sudo apt install -t stretch luajit
sudo apt install -t sid lua-nvim

• Then build:

debchange --newversion 0.2.0debian1-git20170619123516 --distribution unstable "Latest version"
dpkg-buildpackage -rfakeroot -b -d

• Then install both neovim and neovim-runtime package.

Fixes / workarounds

• Broken vertical mode (see below for fix).

Check installation

Start with :checkhealth, this will list many issues related to ruby, python...

Check python support

:echo has('python')
:echo has('python3')

On Windows

• Download release 0.5.0 from pre-built package
• Expand it in C:\bin.
• Add C:\bin\Neovim\bin to env variable PATH.
• Import the following reg file (pending a better solution from here):

Windows Registry Editor Version 5.00

[HKEY_CLASSES_ROOT\*\shell\nvim-qt]
@="Edit with Neovim"
"Icon"="\"C:\\bin\\Neovim\\bin\\nvim-qt.exe\""

[HKEY_CLASSES_ROOT\*\shell\nvim-qt\command]
@="\"C:\\bin\\Neovim\\bin\\nvim-qt.exe\" \"%1\""

[HKEY_CLASSES_ROOT\Directory\shell\nvim-qt]
@="Edit with Neovim"
"Icon"="\"C:\\bin\\Neovim\\bin\\nvim-qt.exe\""

[HKEY_CLASSES_ROOT\Directory\shell\nvim-qt\command]
@="\"C:\\bin\\Neovim\\bin\\nvim-qt.exe\" \"%1\""

• Add to init.vim, to avoid nvim taking ages to close [2]:

set nofsync            " TODO: Add a windows-only test

☒	TODO: nofsync is the default. So find where it is enabled in the init file

• Another cause of slow exit is a corrupted shada folder [3]. Go to C:/Users/.../AppData/Local/nvim-data and delete the folder.

NeoVim GUI

For now, there are no official GUI for Neovim (like gvim). Potential candidates are (see also Neovim related projects):

• neovim-qt
• NyaoVim (an advanced Electron UI based client)
• ONI (another Electron UI based client)
• Use a customized terminal (like Gnome-Terminal)

Criteria for a good GUI:

• Be fast (fast refresh, no jitter in scrolling).
• Drop-in compatible with gvim / vim.
• True color and italic support.
• Blinking cursor (mandatory) and block/caret mode (optional).

Blinking cursor is necessary when using incsearch plugin (or we miss some hightlights).

Terminator + neovim

The best and simplest solution. We use terminator as a gui.

Create the script ngvim:

#! /bin/bash
# Redirect stderr to silent error on keyboard binding failure
2> /dev/null exec /usr/bin/terminator -m --p nvim -i /usr/local/icons/neovim.png -u -x nvim "$@"

This script:

• Sets terminal icon to neovim's.
• Tell terminator to wait until application exits (equivalent to gvim -f)
• Tell terminator not to use Dbus (such that to always appear above current windows).

The advantage of this script is that we use the same back-end as the terminal, and hence we will have the same experience (same features, same bugs).

NyaoVim / ONI

These are Electron-based GUI, under heavy development. They seem to offer rich GUI features (Markdown preview with NyaoVim, rich auto-completion with ONI).

Revisit when:

• Support C/C++ language for auto-completion.

To install, some mantra that helped [4]:

sudo apt install npm
sudo npm install npm@latest -g       # Maybe not needed
sudo npm install react               # Maybe not needed
sudo npm install react@^16.0.0       # Maybe not needed
sudo npm install -g nyaovim --unsafe-perm=true --allow-root

Edit ~/.config/nyaovim/nyaovimrc.html for font:

<neovim-editor 
  id="nyaovim-editor" 
  argv="[[argv]]" 
  font-size="14"
  font="Fantasque Sans Mono,monospace"
  line-height="1.2"
>
</neovim-editor>

neovim-qt

Build from source. Bindings seem old, so we rebuild them:

mkdir build
cd build
cmake ..
make bindings
cmake --build .

Issues

• Cursor not blinking! Using QT API app.setCursorFlashTime(1000); does not help.
• Message Unknown Neovim function "Array vim_get_api_info()". Due to missing/additional bindings. If necessary, we can mute this message in src/function.cpp.

Custom terminal - Gnome-Terminal

The best I could do so far is to create a script gnvim that uses gnome-terminal as window, sets title to NeoVim, and sets icon using xseticon.

To install gnvim:

• Build and install xseticon.

• Copy neovim icon to /usr/local/icons/neovim.png. For instance, there is an icon in neovim-qt.git:

git clone https://github.com/equalsraf/neovim-qt.git
sudo mkdir -p /usr/local/icons
sudo cp neovim-qt/third-party/neovim.png /usr/local/icons

• Create file gnvim, and make it executable:

#! /bin/bash
# We add a sleep 1 because of race condition between xseticon and echo
gnome-terminal --geometry 132x50 --hide-menubar -x bash -c "echo -ne '\033]0;NeoVim\007'; ((sleep 1; xseticon -name NeoVim /usr/local/icons/neovim.png)&); exec nvim $*"

• To add NeoVim GUI as a desktop application, create the file ~/.local/share/applications/neovim.desktop:

#!/usr/bin/env xdg-open

[Desktop Entry]
Version=1.0
Type=Application
Terminal=false
Exec=/home/peetersm/bin/ngvim
Name=NeoVim
Comment=The future of Vim
Icon=/usr/local/icons/neovim.png

Then

chmod a+x ~/.local/share/applications/neovim.desktop

Neovim Gnome-Terminal wrapper

Small wrapper in Python, but it only sets the icon in unity bar, not task switcher.

Tools

neovim-remote

neovim-remote is a replacement for command-line option vim --servername, which is not support by Neovim. It allows for:

• Controlling nvim processes from the shell.
• Opening files from within :terminal without starting a nested nvim process.

Example of uses

In one terminal:

NVIM_LISTEN_ADDRESS=/tmp/nvimsocket nvim

In another terminal:

# Note that nvr uses /tmp/nvimsocket by default
nvr --remote file1 file2            # Open two files
nvr --remote-send 'iabc<esc>'       # Send keys to remote
nvr --remote-expr 'bufname("")'     # Evaluate any VimL expression

Language server

Pyright

To tell pyright to use local virtualenv (! NOT TESTED !) (source: [5]):

require("lspconfig").pyright.setup({
	capabilities = capabilities,
	on_attach = on_attach,
	before_init = function(params, config)
		local Path = require("plenary.path")
		local venv = Path:new((config.root_dir:gsub("/", Path.path.sep)), ".venv")
		if venv:joinpath("bin"):is_dir() then
			config.settings.python.pythonPath = tostring(venv:joinpath("bin", "python"))
		end
	end,
})

Alternatively (source: ChatPGP):

• activate the virtualenv before starting Neovim (simplest, TESTED).
• Create a pyrightconfig.json in project root (TESTED):

{
  "venvPath": "./",
  "venv": "venv"  // or ".venv" if your virtual environment is named .venv
}

• Or update ~/.vimrc:

if has("nvim")
  lua << EOF
  require'lspconfig'.pyright.setup{
    settings = {
      python = {
        venvPath = "./",
        venv = "venv"  -- or ".venv" if your virtual environment is named .venv
      }
    }
  }
  EOF
endif

Tips

Use :term for Read–eval–print loop (REPL)

This can be easily done using a new buffer (C-w v) and a terminal (:term), and then

• Use watch:

watch 'make this && less that'

• Use entr:

echo myfile myotherfile | entr make this

Neovim features

Just a couple of things I should not forget exist.

• Powerful terminal emulation.

• Quick :term git status.
• Use terminal for easy REPL.
• More workflow examples on reddit and SO.

• Incremental substitution (set inccommand=split) (see here).

Troubleshooting

Troubleshooting tips

• Try reproducing without config file: nvim -u NORC.
• Try disabling all plugings. This is more easily done when using a plugin manager (for instance, with vim-plug, comment out Plug lines.

Known GOOD version

On debian:

• neovim_0.2.0debian1-git20170619123516_all.deb

On ubuntu:

• neovim_0.2.0ubuntu1+git201707091951+3517+26~ubuntu16.04.1_amd64.deb
• neovim_0.2.0ubuntu1+git201705081829+3414+24~ubuntu16.04.1_amd64.deb
• neovim_0.1.7ubuntu1+git201704230032+3359+23~ubuntu16.04.1_amd64.deb
• neovim_0.1.7ubuntu1+git201703230754+3253+23~ubuntu16.04.1_amd64.deb
• neovim_0.1.7ubuntu1+git201703122001+3207+23~ubuntu16.04.1_amd64.deb
• neovim_0.1.5ubuntu1+git201612110104+2963+22~ubuntu16.04.1_amd64.deb

Known BROKEN version

• deb

Strange characters appearing when scrolling down in C code (like 38:2:42:161:152m)

• neovim_0.2.0ubuntu1+git201706190001+3482+26~ubuntu16.04.1_amd64.deb

• Issue: broken vertical split
• Issue fixed: See #6816 and #6802

Fix broken vertical mode

Due to bad TERM or COLORTERM env variables #6816 and #6802

Currently I have:

# On gnome-terminal:
echo $TERM / $COLORTERM
# xterm-256color /

# On terminator:
echo $TERM / $COLORTERM
# xterm-256color / truecolor

The fix is to either unset TERM, or set it to gnome-256color, or set COLORTERM to gnome-terminal.

Gnome-Terminal

To fix on Gnome-terminal [6]:

dconf write '/org/gnome/terminal/legacy/profiles:/:b1dcc9dd-5262-4d8d-a863-c897e6d979b9/custom-command' "'env COLORTERM=gnome-terminal /bin/bash'"
dconf write '/org/gnome/terminal/legacy/profiles:/:b1dcc9dd-5262-4d8d-a863-c897e6d979b9/use-custom-command' "true"
# Verify:
dconf dump /org/gnome/terminal/legacy/profiles:/

Changing TERM breaks too many application, so we change instead COLORTERM.

Terminator

We can apply the same trick. Or we can patch terminatorlib/config.py:

-                'colorterm'             : 'truecolor',
+                'term'                  : 'gnome-terminal',

Changing TERM breaks too many application, so we change instead COLORTERM.

Midnight commander

Changing TERM impacts Midnight Commander. Force xterm mode with mc -x. This is no longer needed if we keep TERM as is.

True color and italic support

See xterm.

Regarding terminal support:

• #6802
• #6816

Meta/Alt-key mappings choke (when typed too fast)

See bug #2454.

The solution is too actually install the plugin vim-sensible, contrary to what says :CheckHealth.

This plugins set ttimeoutlen to 100, which is sufficient to have alt-key mappings to act correctly in TUI.

Update

• Now vim-sensible disables ttimeout when it detects neovim :-(. See vim-sensible/#141.

nvim-qt issues

No blinking cursor in nvim-qt

Adding call to QApplication::setCursorFlashTime() in main.cpp does not help. See issue #208.

No support for option 'S' and '-c'

See #224.

Cursor (sometimes) stops blinking

Neovim hard-codes cursor shape and mode. This is tracked in tickets #5740, #5556. See also [Cursor stops blinking #3257], and #4867.

The solution is to use :set guicursor:

:set guicursor=n-v-c:block,i-ci-ve:ver25,r-cr:hor20,o:hor50, \
              n-v-c:blinkwait700-blinkoff400-blinkon250, \
              sm:block-blinkwait175-blinkoff150-blinkon175

Undefined variable: self

See issue #5763.

Last known good version without this bug for me: neovim_0.1.5ubuntu1+git201612110104+2963+22~ubuntu16.04.1_amd64.deb.

Bug fixed, but must update all plugins (:PlugUpdate) and vim-plug itself (with :PlugUpgrade).

incsearch plugin broken

See issue #125.

Shift-enter not working in TUI

This requires a terminal that can configure CSI (like iTerm2). Maybe [pangoterm] is another option.

See also:

• https://www.bountysource.com/issues/1428857-fix-ambiguous-terminal-key-strokes

Neovim not resizing correctly in Terminator on split

See bug 6156.

"E724: unable to correctly dump variable with self-referencing container" when using incsearch

See bug 5902. My fork on GitHub contains a workaround.

• FIXED in latest incsearch release.

YouCompleteMe semantic engine causes spurious buffer scrolling

Typind a dot . in CPP code causes spurious buffer scrolling. Edited line usually ends up at the bottom of the editing window, which is inconvenient.

This happens in NeoVim, but not in gvim. Also the semantic engine was not actually running.

To fix, disable semantic completion:

let g:ycm_filetype_specific_completion_to_disable = {
      \ 'cpp': 1,
      \ 'gitcommit': 1
      \}

Strange ESC sequence characters appearing when scrolling

Strange characters appearing when scrolling down in C code (like 38:2:42:161:152m).

Occurred in version:

• 0.2.0ubuntu1+git201709190613+3649+26~ubuntu16.04.1.

Github:

• Issue #7381.

To reproduce the problem:

• create file tmp.c with

for((j=0;j<128;j++)); do echo "{ $(for((i=0;i<17;i++)); do echo -n '0x00, '; done) }"; done > tmp2.c

• Edit the file again. Bug will occur on display.

The minimum .vimrc to reproduce:

call plug#begin('~/.vim/plugged')
Plug 'xeyownt/vim-colors-solarized'
call plug#end()
if has('nvim')
  set termguicolors
endif
colorscheme solarized

It also requires using my fork of vim-colors-solarized (commit 6d72acc).

Another minimum .vimrc to reproduce:

call plug#begin('~/.vim/plugged')
Plug 'Icymind/NeoSolarized'
call plug#end()
if has('nvim')
  set termguicolors
endif
colorscheme NeoSolarized
hi! MatchParen gui=NONE,underline,bold cterm=NONE,underline,bold guifg=#dc322f ctermfg=1 guibg=#eee8d5 ctermbg=7

Alternatively, remove the last line, and patch NeoSolarized with:

-exe "hi! MatchParen"     .s:fmt_bold   .s:fg_red    .s:bg_base01
+exe "hi! MatchParen"     .s:fmt_undb   .s:fg_red    .s:bg_base02

The bug does not occur when patching with:

-exe "hi! MatchParen"     .s:fmt_bold   .s:fg_red    .s:bg_base01
+exe "hi! MatchParen"     .s:fmt_bold   .s:fg_red    .s:bg_base02

This corresponds to executing line line

hi! MatchParen gui=NONE,bold cterm=NONE,bold guifg=#dc322f ctermfg=1 guibg=#eee8d5 ctermbg=7

Slow navigation / edition in "big" files (>1000 lines)

• Issue — vim-gitgutter slows down editing.

Workaround: Simply commit more frequently to reduce diffs.

The culprit is plugin vim-gitgutter. To identify the culprit, we run the vim profiler [7]:

:profile start profile.log
:profile func *
:profile file *
" At this point do slow actions
:profile pause
:noautocmd qall!

Looking in the log, we see that

• gitgutter#async#handle_diff_job_nvim took 5.7s on 18 calls,
• gitgutter#sign#remove_signs took 2.65s on 12 calls,
• gitgutter#sign#upsert_new_gitgutter_signs took 2.7s on 12 calls,
• gitgutter#sign#update_signs took 5.51s on 12 calls,
• gitgutter#handle_diff() took 5.7s on 12 calls,

More information on how to profile gitgutter: https://github.com/airblade/vim-gitgutter/wiki/How-to-profile-vim-gitgutter. Related issue:

• #335.
• #184.

Blinking cursor disappearing when extending selection in visual mode

• Issue — Blinking cursor disappearing when extending selection in visual mode.
• Wordaround — Install neovim from http://ppa.launchpad.net/neovim-ppa/stable/ubuntu (eg. release 0.3.1-3ppa1~ubuntu16.04.5).

When starting a visual selection with a blinking cursor (configured as detailed above), the cursor disappears when extending the selection. Moreover the cursor color is incorrect (same as selection, when normally it is darker). As a result, the selection is often extended too far because of the lack of visual selection end.

Problem appeared around release 0.3.1+ubuntu2+git201901082045-c8e78ab-7936b7b-8c67d57~ubuntu16.04.1 (from http://ppa.launchpad.net/neovim-ppa/unstable/ubuntu). Last known good release was around release 0.3.1+ubuntu2+git201812041937-7e97587-7936b7b-8c67d57~ubuntu16.04.1.

new — I again have this issue in nvim 0.4.4 built from source, on Debian Buster. I think I didn't have that issue with the default nvim installed with Buster (0.3.4-3)

• It seems to be due to some settings in my .vimrc. Issue disappear with an empty .vimrc.
• Fix: update the settings for guicursor (see help guicursor for the configuration to use for blinking cursor).

Failed to load python host ...

This error may occur if a conflicting Python environment is currently active in the shell / session.

To force use of a particular python host:

let g:python_host_prog  = '/usr/bin/python'  " Avoid conflict if other pyenv is activated
let g:python3_host_prog = '/usr/bin/python3' " Avoid conflict if other pyenv is activated

Slow startup due to clipboard / xsel timeout

NEW — xclip gives better boot time but has clipboard sync issues. Alternative fixes:

• Define g:clipboard appropriately to used xsel instead.

vim.g.clipboard = {
  copy = {
    ["+"] = "xsel -i -b",
    ["*"] = "xsel -i -p",
  },
  paste = {
    ["+"] = "xsel -o -b 2>/dev/null",
    ["*"] = "xsel -o -p 2>/dev/null",
  },
}

• Edit /usr/local/share/nvim/runtime/autoload/provider/clipboard.vim and remove xsel test:

+  elseif exists('$DISPLAY') && executable('xsel')
-  elseif exists('$DISPLAY') && executable('xsel') && s:cmd_ok('xsel -o -b')

• Install xclip [8] (see also Common Issues):

sudo apt install xclip

• new: Note that xclip has sync issue and is less maintained than xsel.

To Do

• Find a good TUI or GUI

• Try again Alacritty to see if speed issue on Intel MESA is solved.
• Follow up neovim-qt

• Test advanced linters plugins like neomake and syntactics.