Faq
Nvim :help pages, generated
from source
using the tree-sitter-vimdoc parser.
Frequently asked Questions
WHERE SHOULD I PUT MY CONFIG (VIMRC)?
HOW STABLE IS THE DEVELOPMENT (PRE-RELEASE) VERSION?
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.
CAN I USE LUA-BASED VIM PLUGINS (E.G. NEOCOMPLETE)?
HOW CAN I USE "TRUE COLOR" IN THE TERMINAL?
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
NVIM SHOWS WEIRD SYMBOLS (�[2 q) WHEN CHANGING MODES
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.
HOW TO CHANGE CURSOR SHAPE IN THE TERMINAL?
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.
HOW TO CHANGE CURSOR COLOR IN THE TERMINAL?
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
CURSOR STYLE ISN'T RESTORED AFTER EXITING OR SUSPENDING AND RESUMING NVIM
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
\,a:blinkwait700-blinkoff400-blinkon250-Cursor/lCursor
\,sm:block-blinkwait175-blinkoff150-blinkon175
au VimLeave,VimSuspend * set guicursor=a:block-blinkon0
CURSOR SHAPE DOESN'T CHANGE IN TMUX
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
WHAT HAPPENED TO --remote AND FRIENDS?
COPYING TO X11 PRIMARY SELECTION WITH THE MOUSE DOESN'T WORK
MY CTRL-H MAPPING DOESN'T WORK
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).
<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
PYTHON SUPPORT ISN'T WORKING
Other hints:
Be sure you have the latest version of the
pynvim Python module:
uv tool install --upgrade pynvim
See
provider-python for other installation options.
If you're manually creating a Python virtual environment for the
pynvim module
https://pypi.org/project/pynvim/, you must set
g:python3_host_prog to
the virtualenv's interpreter path.
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.
The python neovim module was renamed to pynvim (long ago).
:CHECKHEALTH REPORTS E5009: INVALID $VIMRUNTIME
$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.
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 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
COLORS AREN'T DISPLAYED CORRECTLY
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.
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, you might not be using a UTF-8 locale. See these issues:
ESC IN TMUX OR GNU SCREEN IS DELAYED
.tmux.conf:
set -g escape-time 10
# Or for tmux >= 2.6
set -sg escape-time 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 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.
ESC IN GNU SCREEN IS LOST WHEN MOUSE MODE IS ENABLED
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.
CALLING INPUTLIST(), ECHOMSG, ... IN FILETYPE PLUGINS AND AUTOCMD DOES NOT WORK
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.'
G:CLIPBOARD SETTINGS ARE NOT USED.
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
endif
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
endif
runtime autoload/provider/clipboard.vim
endfunction
if !exists('s:loaded")
call dictwatcheradd(g:, 'clipboard', function('s:clipboard_changed'))
endif
let s:loaded = v:true
Run make distclean && make to rule out a stale build environment causing the
failure.
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.
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.
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
WHY NOT USE JSON FOR RPC?
JSON cannot easily/efficiently handle binary data
WHY EMBED LUA INSTEAD OF X?
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.
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:
WHY LUA 5.1 INSTEAD OF LUA 5.3+?
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.
WILL NEOVIM TRANSLATE VIMSCRIPT TO LUA, INSTEAD OF EXECUTING VIMSCRIPT DIRECTLY?
ARE PLUGIN AUTHORS ENCOURAGED TO PORT THEIR PLUGINS FROM VIMSCRIPT TO LUA? DO YOU PLAN ON SUPPORTING VIMSCRIPT INDEFINITELY? (#1152)
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.
That being said, reimplementing legacy plugins in Lua in order to make use of
Nvim API and to integrate with Nvim-specific features such as treesitter can
be worthwhile.