Justin M. Keyes edited this page Mar 14, 2017 · 101 revisions

Note: :CheckHealth detects and resolves many of the problems in this FAQ. Try it!

Something broke after upgrading Neovim?

See Following-HEAD, which documents breaking changes.

Where should I put my config (vimrc)?

The default config file location is:


You can copy your existing vimrc there, or symlink to it. :help nvim-from-vim

Can I use Ruby-based Vim plugins (e.g. LustyExplorer)?

Yes, starting with Neovim 0.1.5 PR #4980 the legacy Vim if_ruby interface is supported.

Can I use Lua-based Vim plugins (e.g. neocomplete)?

Yes, starting with Neovim 0.2 PR #4411 Lua is built-in.

How can I use true colors in the terminal?

Add this to your init.vim:

set termguicolors

See this gist for more information about true colors, such as what terminals support it.

How can I change the cursor shape in the terminal?

In man nvim see the note about NVIM_TUI_ENABLE_CURSOR_SHAPE.

Since Nvim 0.2, mode-sensitive cursor-shape is enabled by default (if your terminal supports it).

To disable cursor-shape, put this in your init.vim:


To enable blinking cursor-shape, put this in your init.vim:


The Vim terminal settings t_SI and t_EI (which are non-standard) are ignored, like all other t_XX settings.

Note about gnome-terminal 3.6.2 (libvte-2.90-9): #2537

Cursor shape doesn't change in tmux

Add this to your .tmux.config:

set -g -a terminal-overrides ',*:Ss=\E[%p1%d q:Se=\E[2 q'

See #3165 for discussion.

Is Windows supported?

Yes, starting with the 0.2 release. See the Install page.

What happened to --remote and friends?

The code for that family of command-line arguments was removed. It may eventually be reimplemented using the Neovim API, but for now the script neovim-remote can be used instead.

See #1750 for more information.

Runtime issues

clipboard: provider is not available

Make sure that Neovim can find its runtime.

My CTRL-H mapping doesn't work

This was fixed in Neovim 0.2. If you are running Neovim 0.1.7 or older, adjust your terminal's "kbs" (key_backspace) terminfo entry:

infocmp $TERM | sed 's/kbs=^[hH]/kbs=\\177/' > $TERM.ti
tic $TERM.ti

<Home> or some other "special" key doesn't work

Make sure $TERM is set correctly.

  • For screen or tmux, TERM should be screen-256color (Not xterm-256color)
  • In other cases if "256" does not appear in the string it's probably wrong. Try TERM=xterm-256color.

:! and system() do weird things with interactive processes

Interactive commands are supported by :terminal in Neovim. But :! and system() do not support interactive commands, primarily because Neovim UIs use stdio for msgpack communication, but also for performance, reliability, and consistency across platforms (see :help gui-pty).

See also #1496

Python support isn't working

Run :CheckHealth (available in 0.1.5) inside Neovim for automatic diagnosis.

Additional hints:

  • If you are using pyenv or virtualenv for the neovim python module, you must set g:python_host_prog and/or g:python3_host_prog to the virtualenv's interpreter path.
  • Read :help provider-python.
  • Be sure you have the latest version of the neovim Python module.
pip  install --upgrade neovim
pip2 install --upgrade neovim
pip3 install --upgrade neovim
  • Try with nvim -u NORC to make sure your init.vim isn't causing a problem. If you get E117: Unknown function, that means Neovim can't find its runtime.

Neovim can't find its runtime

This is the case if :help nvim shows E149: Sorry, no help for nvim.

Make sure that $VIM and $VIMRUNTIME point to Neovim's (as opposed to Vim's) runtime by checking :echo $VIM and :echo $VIMRUNTIME. This should give something like /usr/share/nvim resp. /usr/share/nvim/runtime.

Also make sure that you don't accidentally overwrite your runtimepath (:set runtimepath?), which includes the above $VIMRUNTIME by default (see :help 'runtimepath').

E518: Unknown option: [option]

Some very old/unnecessary options have been removed from Neovim. See :help nvim-features-removed for the complete list.

Neovim is slow

Make sure you're running an optimized build of nvim. :CheckHealth nvim should report one of these "build types":

Build type: RelWithDebInfo
Build type: MinSizeRel
Build type: Release

If it reports Build type: Debug and you're building Neovim from source, see Building Neovim#optimized-builds.
If you're using a third-party package, please inform the maintainer.

Colors aren't displayed correctly

From a shell, run TERM=xterm-256color nvim. If colors are displayed correctly, then export that value of TERM in your user profile (usually ~/.profile):

export TERM=xterm-256color

If you're using tmux, instead add this to your tmux.conf:

set -g default-terminal "screen-256color"

Some tmux users may need to instead use:

set -g default-terminal "screen-256color-bce"

For GNU screen, configure your .screenrc:

term screen-256color

Note: Neovim ignores t_Co and other terminal codes.

Neovim can't read UTF-8 characters

Run the following from the command line:

locale | grep -E '(LANG|LC_CTYPE|LC_ALL)=(.*\.)?(UTF|utf)-?8'

If there's no results, then you might not be using a UTF-8 locale. See the following issues: #1601 #1858 #2386

ESC in tmux or GNU Screen is delayed

This is a common problem in tmux / screen (see also tmux/#131). The corresponding timeout needs to be tweaked to a low value (10-20ms).


set -g escape-time 10


maptimeout 10

"Why doesn't this happen in Vim?"

It does happen (try vim -N -u NONE), but if you hit a key quickly after ESC then Vim interprets the ESC as its own key. This means you won't notice the delay unless you closely observe the cursor. The difference is that Vim won't understand ALT (META) key-chords, so for example nnoremap <M-a> won't work. ALT (META) key-chords always work in Nvim. See also Vim's own documentation:

:help xterm-cursor-keys

Installation issues

Generating helptags failed

If re-installation fails with Generating helptags failed, try removing the previously installed runtime directory (if CMAKE_INSTALL_PREFIX is not set during building, the default is /usr/local/share/nvim):

# rm -r /usr/local/share/nvim

Build issues

General build issues

Run make distclean && make to rule out a stale build environment causing the failure.

Proxy issues #2482

If your machine is behind a network proxy and you see this error:

Error: Failed installing dependency: https://rocks.moonscript.org/penlight-1.3.2-2.rockspec 
Error fetching file: Failed downloading http://stevedonovan.github.io/files/penlight-1.3.2-core.zip 

this can be fixed by setting the https_proxy environment variable (for cURL).

Settings in local.mk don't take effect

CMake caches build settings, so you might need to run rm -r build && make after modifying local.mk.

CMake errors

configure_file Problem configuring file

This is probably a permissions issue, which can happen if you run make as the root user, then later run an unprivileged make. To fix this, run rm -rf build and try again.

A suitable Lua interpreter was not found.

This can be caused by a local LuaRocks installation. Try unsetting the LUA_PATH and LUA_CPATH environment variables (via unset) before building.

Lua packages

The Lua packages required by the build process should be automatically installed by LuaRocks (invoked by CMake automatically), but sometimes this will fail. Generally, this means either:

  • The LuaRocks servers are down.
  • The program unzip isn't found. If this is the case, LuaRocks will report something like this: Warning: Failed searching manifest: Failed loading manifest: Failed extracting manifest file.
  • The CDPATH environment variable is interfering with the build, so it should be unset prior to running make.

To avoid the first error, a LuaRocks mirror can be used by creating the file .deps/usr/etc/luarocks/config-5.1.lua with the following contents:


After that, run make cmake.

Failing the above, you can always try installing the following packages manually:

Keep in mind that some of those packages have their own dependencies which also have to be installed, and the version you install hasn't necessarily been tested to work with Neovim.


Why not use JSON for RPC?

Why was Lua chosen for writing tests and implementing VimL?

Lua is a very small language, but it provides everything we need to implement a language like VimL, which was created to configure and script the editor. The biggest advantage that languages like Python or Ruby have over Lua are their huge library collections, but that isn't a factor for our main use case which is to remove thousands of lines of C by using Lua as a VimL runtime.

See also these articles about Lua:

Lua and VimL are distinct languages with different semantics, how can Lua be used as a runtime for VimL?

The idea is to make Neovim completely scriptable using Lua. Unlike the Lua interface to Vim, this new implementation needs to have the same power as VimL, with APIs for defining syntax rules, etc. Then a VimL-to-Lua translator will be implemented, with the generated code targeting the new Lua API.

Won't it be slower to translate VimL to Lua, instead of executing VimL directly?

We'll use LuaJIT, the fastest scripting runtime out there. Parsing an additional language will create some overhead, but that will be insignificant compared to the runtime performance improvements, because Vimscript is so slow. Plugins may even run faster.

Update (2016): PR #243 implements the VimL-to-Lua translator. But it is blocked indefinitely by technical concerns. Much of the work in that PR will be re-used/re-purposed (viz. typval_T/vim_to_object refactor and eval.c refactor).

Are plugin authors encouraged to port their plugins from Vimscript to Lua? Do you plan on supporting Vimscript indefinitely? (#1152)

We don't anticipate any reason to deprecate Vimscript, which is a valuable DSL for text-editing tasks. Maintaining Vimscript compatibility is less costly than a mass migration of existing Vim plugins.

Porting from Vimscript to Lua just for the heck of it gains nothing. Neovim is emphatically a fork of Vim in order to leverage the work already spent on thousands of Vim plugins, while enabling new types of plugins and integrations.