Nvim :help pages, generated from source using the tree-sitter-vimdoc parser.

Frequently asked Questions
See config; you can copy (or symlink) your existing vimrc. nvim-from-vim
The unstable (pre-release) https://github.com/neovim/neovim/releases/tag/nightly version of Nvim ("HEAD", i.e. the master branch) is used to aggressively stage new features and changes. It's usually stable, but will occasionally break your workflow. We depend on HEAD users to report "blind spots" that were not caught by automated tests.
Use the stable (release) https://github.com/neovim/neovim/releases/latest version for a more predictable experience.
No. Starting with Nvim 0.2 PR #4411 https://github.com/neovim/neovim/pull/4411 Lua is built-in, but the legacy Vim if_lua interface is not supported.
Truecolor (24bit colors) are enabled by default if a supporting terminal is detected. If your terminal is not detected but you are sure it supports truecolor, add this to your init.vim:
set termguicolors
This is a bug in your terminal emulator. It happens because Nvim sends cursor-shape termcodes by default, if the terminal appears to be xterm-compatible (TERM=xterm-256color).
To workaround the issue, you can:
Use a different terminal emulator
Disable 'guicursor' in your Nvim config:
:set guicursor=
" Workaround some broken plugins which set guicursor indiscriminately.
:autocmd OptionSet guicursor noautocmd set guicursor=
See also $TERM for recommended values of $TERM.
For Nvim 0.1.7 or older: see the note about NVIM_TUI_ENABLE_CURSOR_SHAPE in man nvim.
For Nvim 0.2 or newer: cursor styling is controlled by the 'guicursor' option.
To _disable_ cursor-styling, set 'guicursor' to empty:
:set guicursor=
" Workaround some broken plugins which set guicursor indiscriminately.
:autocmd OptionSet guicursor noautocmd set guicursor=
If you want a non-blinking cursor, use blinkon0. See 'guicursor'.
'guicursor' is enabled by default, unless Nvim thinks your terminal doesn't support it. If you're sure that your terminal supports cursor-shaping, set 'guicursor' in your init.vim, as described in 'guicursor'.
The Vim terminal options t_SI and t_EI are ignored, like all other t_xx options.
Old versions of libvte (gnome-terminal, roxterm, terminator, ...) do not support cursor style control codes. #2537 https://github.com/neovim/neovim/issues/2537
Cursor styling (shape, color, behavior) is controlled by 'guicursor', even in the terminal. Cursor color (as opposed to shape) only works if 'termguicolors' is set.
'guicursor' gives an example, but here's a more complicated example which sets different colors in insert-mode and normal-mode:
:set termguicolors
:hi Cursor guifg=green guibg=green
:hi Cursor2 guifg=red guibg=red
:set guicursor=n-v-c:block-Cursor/lCursor,i-ci-ve:ver25-Cursor2/lCursor2,r-cr:hor20,o:hor50
Terminals do not provide a way to query the cursor style. Use autocommands to manage the cursor style:
au VimEnter,VimResume * set guicursor=n-v-c:block,i-ci-ve:ver25,r-cr:hor20,o:hor50
au VimLeave,VimSuspend * set guicursor=a:block-blinkon0
tmux decides that, not Nvim. See tui-cursor-shape for a fix.
See #3165 https://github.com/neovim/neovim/pull/3165 for discussion.
If cursor _ appears and disappears very quickly when opening nvim without a document under tmux, and you set ctermbg in EndOfBuffer and Normal, try setting these to NONE:
hi EndOfBuffer ctermbg=NONE ctermfg=200 cterm=NONE
hi Normal ctermbg=NONE ctermfg=200 cterm=NONE
--remote is partly supported. clientserver
If you require flags from Vim that are missing in Nvim, you can use https://github.com/mhinz/neovim-remote instead.
clipboard=autoselect is not implemented yet https://github.com/neovim/neovim/issues/2325. You may find this workaround to be useful:
vnoremap <LeftRelease> "*ygv
vnoremap <2-LeftRelease> "*ygv
This was fixed in Nvim 0.2. If you are running Nvim 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
(Feel free to delete the temporary *.ti file created after running the above commands).
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.
Interactive commands are supported by :terminal in Nvim. But :! and system() do not support interactive commands, primarily because Nvim UIs use stdio for msgpack communication, but also for performance, reliability, and consistency across platforms (see https://vimhelp.org/gui_x11.txt.html#gui-pty).
Run :checkhealth in Nvim for automatic diagnosis.
Other hints:
The python neovim module was renamed to pynvim (long ago).
If you're using pyenv or virtualenv for the pynvim module https://pypi.python.org/pypi/pynvim/, you must set g:python3_host_prog to the virtualenv's interpreter path.
Be sure you have the latest version of the pynvim Python module:
python -m pip install setuptools
python -m pip install --upgrade pynvim
python3 -m pip install --upgrade pynvim
Try with nvim -u NORC to make sure your config (init.vim) isn't causing a problem. If you get E117: Unknown function, that means there's a runtime issue: faq-runtime.
This means health#check() couldn't load, which suggests that $VIMRUNTIME or 'runtimepath' is broken.
$VIMRUNTIME must point to Nvim's runtime files, not Vim's.
The $VIMRUNTIME directory contents should be readable by the current user.
Verify that :echo &runtimepath contains the $VIMRUNTIME path.
Check the output of:
:call health#check()
:verbose func health#check
This is the case if :help nvim shows E149: Sorry, no help for nvim.
Make sure that $VIM and $VIMRUNTIME point to Nvim'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 'runtimepath').
Use a fast terminal emulator:
Use an optimized build:
: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 Nvim from source, see https://github.com/neovim/neovim/blob/master/BUILD.md.
Ensure that $TERM is set 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 "tmux-256color"
For GNU screen, configure your .screenrc <https://wiki.archlinux.org/index.php/GNU_Screen#Use_256_colors>:
term screen-256color
NOTE: Nvim ignores t_Co and other t_xx terminal codes.
Run the following from the command line:
locale | grep -E '(LANG|LC_CTYPE|LC_ALL)=(.*\.)?(UTF|utf)-?8'
This is a common problem https://www.google.com/?q=tmux%20vim%20escape%20delay in tmux / screen (see also https://github.com/tmux/tmux/issues/131#issuecomment-145853211). The corresponding timeout needs to be tweaked to a low value (10-20ms).
set -g escape-time 10
# Or for tmux >= 2.6
set -sg escape-time 10
maptimeout 10
It does happen (try vim -N -u NONE), but if you hit a key quickly after ESC then Vim interprets the ESC as ESC instead of ALT (META). You won't notice the delay unless you closely observe the cursor. The tradeoff 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 :help xterm-cursor-keys in Vim.
Nvim 0.3 mimics the Vim behavior while still fully supporting ALT mappings. See i_ALT.
This happens because of a bug in screen https://savannah.gnu.org/bugs/?60196 : in mouse mode, screen assumes that ESC is part of a mouse sequence and will wait an unlimited time for the rest of the sequence, regardless of maptimeout. Until it's fixed in screen, there's no known workaround for this other than double-pressing escape, which causes a single escape to be passed through to Nvim.
This is because Nvim sets shortmess+=F by default. Vim behaves the same way with set shortmes+=F. There are plans to improve this, but meanwhile as a workaround, use set shortmess-=F or use unsilent as follows.
unsilent let var = inputlist(['1. item1', '2. item2'])
autocmd BufNewFile * unsilent echomsg 'The autocmd has been fired.'
If the clipboard provider is already loaded, you will need to reload it after configuration. Use the following configuration.
let g:clipboard = { 'name' : ... }
if exists('g:loaded_clipboard_provider')
  unlet g:loaded_clipboard_provider
  runtime autoload/provider/clipboard.vim
Or, if you want automatic reloading when assigning to g:clipboard, set init.vim as follows.
function! s:clipboard_changed(...) abort
  if exists('g:loaded_clipboard_provider')
    unlet g:loaded_clipboard_provider
  runtime autoload/provider/clipboard.vim
if !exists('s:loaded")
  call dictwatcheradd(g:, 'clipboard', function('s:clipboard_changed'))
let s:loaded = v:true
Run make distclean && make to rule out a stale build environment causing the failure.
CMake caches build settings, so you might need to run rm -r build && make after modifying local.mk.
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.
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
JSON cannot easily/efficiently handle binary data
JSON specification is ambiguous: https://seriot.ch/parsing_json.php
Lua is a very small language, ideal for embedding. The biggest advantage of Python/Ruby/etc is their huge collection of libraries, but that isn't relevant for Nvim, where Nvim is the "batteries included" library: introducing another stdlib would be redundant.
Lua 5.1 is a complete language: the syntax is frozen. This is great for backwards compatibility.
Nvim also uses Lua internally as an alternative to C. Extra performance is useful there, as opposed to a slow language like Python or Vim9script.
LuaJIT is one of the fastest runtimes on the planet, 10x faster than Python and "Vim9script" https://vimhelp.org/vim9.txt.html , 100x faster than Vimscript.
Python/JS cost more than Lua in terms of size and portability, and there are already numerous Python/JS-based editors. So Python/JS would make Nvim bigger and less portable, in exchange for a non-differentiating feature.
See also:
Lua 5.1 is a different language than 5.3. The Lua org makes breaking changes with every new version, so even if we switched (not upgraded, but switched) to 5.3 we gain nothing when they create the next new language in 5.4, 5.5, etc. And we would lose LuaJIT, which is far more valuable than Lua 5.3+.
Lua 5.1 is a complete language. To "upgrade" it, add libraries, not syntax. Nvim itself already is a pretty good "stdlib" for Lua, and we will continue to grow and enhance it. Changing the rules of Lua gains nothing in this context.
We are experimenting with vim9jit https://github.com/tjdevries/vim9jit to transpile Vim9script (Vim9's Vimscript variant) to Lua and have used this to port Vim9 plugins https://github.com/neovim/neovim/pull/21662 to Nvim Lua.
We have no plans for transpiling legacy Vimscript.
We don't anticipate any reason to deprecate Vimscript, which is a valuable DSL https://en.wikipedia.org/wiki/Domain-specific_language 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. Nvim 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.
Commands index
Quick reference