:help pages, generated
using the tree-sitter-vimdoc parser.
Differences between Nvim and Vim
Nvim differs from Vim in many ways, although editor and Vimscript (not
Vim9script) features are mostly identical. This document is a complete and
centralized reference of the differences.
for your config
$XDG_CONFIG_HOME/nvim instead of
.vim to store configuration files.
session information. shada
Filetype detection is enabled by default. This can be disabled by adding
":filetype off" to init.vim
Syntax highlighting is enabled by default. This can be disabled by adding
":syntax off" to init.vim
defaults to "dark" (unless set automatically by the terminal/UI)
defaults to .,~/.local/state/nvim/backup// (xdg
defaults to ~/.local/state/nvim/swap// (xdg
defaults (in effect) to "vert:│,fold:·,sep:│"
defaults to "./tags;,tags"
defaults to ~/.local/state/nvim/undo// (xdg
plugin is enabled, .editorconfig settings are applied.
plugin is enabled, so :Man
is available by default.
matchit plugin is enabled. To disable it in your config:
:let loaded_matchit = 1
By default the mouse is enabled, and
opens a popup-menu
standard actions ("Cut", "Copy", "Paste", …). Mouse is NOT enabled in
or the more-prompt
, so you can temporarily disable it just by
If you don't like this you can disable the mouse in your config
using any of
Disable mouse completely by unsetting the 'mouse'
extends selection instead of showing popup-menu:
releases mouse until the cursor moves:
nnoremap <A-LeftMouse> <Cmd>
\ set mouse=<Bar>
\ echo 'mouse OFF until next cursor-move'<Bar>
\ autocmd CursorMoved * ++once set mouse&<Bar>
\ echo 'mouse ON'<CR>
To remove the "How-to disable mouse" menu item and the separator above it:
aunmenu PopUp.How-to\ disable\ mouse
Nvim creates the following default mappings at startup
. You can disable any
of these in your config by simply removing the mapping, e.g. ":unmap Y".
nnoremap Y y$
nnoremap <C-L> <Cmd>nohlsearch<Bar>diffupdate<Bar>normal! <C-L><CR>
inoremap <C-U> <C-G>u<C-U>
inoremap <C-W> <C-G>u<C-W>
xnoremap * y/\V<C-R>"<CR>
xnoremap # y?\V<C-R>"<CR>
nnoremap & :&&<CR>
Default autocommands exist in the following groups. Use ":autocmd!
remove them and ":autocmd
" to see how they're defined.
CmdwinEnter: Limits syntax sync to maxlines=1 in the cmdwin
New Features nvim-features
Working intuitively and consistently is a major goal of Nvim.
Nvim always includes ALL features, in contrast to Vim (which ships various
combinations of 100+ optional features). feature-compile
Think of it as
a leaner version of Vim's "HUGE" build. This reduces surface area for bugs,
and removes a common source of confusion and friction for users.
Nvim avoids features that cannot be provided on all platforms; instead that
is delegated to external plugins/extensions. E.g. the
option is "sometimes" available in Vim (with potential surprises:
Vim's internal test functions (test_autochdir(), test_settime(), etc.) are
not exposed (nor implemented); instead Nvim has a robust API.
Behaviors, options, documentation are removed if they cost users more time
than they save.
Usability details have been improved where the benefit outweighs any
backwards-compatibility cost. Some examples:
Terminal features such as 'guicursor'
are enabled where possible.
Some features are built in that otherwise required external plugins:
The Nvim UI is "decoupled" from the core editor: all UIs, including the
are just plugins that connect to a Nvim server (via --server
). Multiple Nvim UI clients can connect to the same Nvim editor
External plugins run in separate processes. remote-plugin
stability and allows those plugins to work without blocking the editor. Even
"legacy" Python and Ruby plugins which use the old Vim interfaces (if_pyth
) run out-of-process.
Platform and I/O facilities are built upon libuv. Nvim benefits from libuv
features and bug fixes, and other projects benefit from improvements to libuv
by Nvim developers.
The expression prompt (@=
) is highlighted
using a built-in Vimscript expression parser. expr-highlight
support custom highlighting. input()-highlight
(Experimental) Command-line (:
) is colored by callback defined in
(this callback is for testing only, and will be
removed in the future).
is always available
is available by default, with many improvements such as completion
can be invoked before highlight group is defined
works with Lua
User commands can support :command-preview
to show results as you type
with "++p" flag creates parent directories.
) chords always work (even in the TUI
). Map |<M-| with any key:
are two different keycodes.
shows a filetype-defined "outline" of the current buffer.
replays the last recorded macro instead of switching to Ex mode (gQ
searches for ".nvim.lua", ".nvimrc", or ".exrc" files. The
user is prompted whether to trust the file.
flags: "msgsep", "horiz", "horizup",
"horizdown", "vertleft", "vertright", "verthoriz"
supports up to 9 dynamic/fixed columns
works in the terminal (TUI)
shows interactive results for :substitute
"view" tries to restore the mark-view
when moving through
or using mark-motions
global statusline support
amount to scroll by when scrolling with a mouse
"F" flag does not affect output from autocommands
supports up to 9 dynamic/fixed columns
full control of columns using 'statusline'
supports unlimited alignment sections
%X can call any function on mouse-click
behavior was simplified
pseudo-transparency in floating windows api-floatwin
Shell output (:!
, …) is always routed through the UI, so it
cannot "mess up" the screen. (You can still use "chansend(v:stderr,…)" if
you want to mess up the screen :)
Nvim throttles (skips) messages from shell commands (:!
if there is too much output. No data is lost, this only affects display and
improves performance. :terminal
output is never throttled.
does not support "interactive" commands. Use :terminal
(GUI Vim has a similar limitation, see ":help gui-pty" in Vim.)
:!start is not special-cased on Windows.
does not support writing/reading "backgrounded" commands. E5677
Signs are removed if the associated line is deleted.
invoke the same "improved Ex mode" as -E and -Es.
read stdin as text (into buffer 1).
have improved behavior:
Quits automatically, don't need "-c qa!".
Skips swap-file dialog.
reads Normal commands from stdin if the script name is "-".
Reading text (instead of commands) from stdin --
works by default: "-" file is optional
works in more cases: -Es
, file args
Start Nvim with 'verbose'
level 3 to show terminal capabilities:
reflects the terminal type derived from $TERM
and other environment
checks. For debugging only; not reliable during startup.
"builtin_x" means one of the builtin-terms
was chosen, because the expected
terminfo file was not found on the system.
Nvim will use 256-colour capability on Linux virtual terminals. Vim uses
only 8 colours plus bright foreground on Linux VTs.
Vim combines what is in its builtin-terms
with what it reads from terminfo,
and has a 'ttybuiltin'
setting to control how that combination works. Nvim
uses one or the other, it does not attempt to merge the two.
messages: When showing messages longer than 'cmdheight'
scroll the message lines, not the entire screen. The
separator line is decorated by hl-MsgSeparator
the "msgsep" flag of 'fillchars'
is always absolute ("full")
is always available (for use by external UIs)
Upstreamed features nvim-upstreamed
These Nvim features were later integrated into Vim.
flags: "pum" enables popupmenu for wildmode completion
works with anonymous (no file) scripts
Changed features nvim-changed
This section lists various low-level details about other behavior changes.
1. Assuming /tmp/foo does not exist and /tmp can be written to
mkdir('/tmp/foo/bar', 'p', 0700) will create both /tmp/foo and /tmp/foo/bar
with 0700 permissions. Vim mkdir will create /tmp/foo with 0755.
2. If you try to create an existing directory with
'p')) mkdir() will silently exit. In Vim this was an error.
3. mkdir() error messages now include strerror() text when mkdir fails.
1. No maximum recursion depth limit is applied to nested container
fails immediately on nested containers, not when recursion limit
2. When :echo
encounters duplicate containers like
let l = 
echo [l, l]
it does not use "[...]" (was: "[, [...]]", now: "[, ]"). "..." is
only used for recursive containers.
printing nested containers adds "@level" after "..." designating
the level at which recursive container was printed: :echo-self-refer
Same thing applies to string()
(though it uses construct like
}"), but this is not reliable because string()
4. Stringifyed infinite and NaN values now use str2float()
and can be evaled
5. (internal) Trying to print or stringify VAR_UNKNOWN in Vim results in
nothing, E908, in Nvim it is internal error.
Viminfo text files were replaced with binary (messagepack) shada
now limits size of every item and not just registers.
option got renamed to 'shada'
. Old option is kept as an alias for
ShaDa file format was designed with forward and backward compatibility in
Some errors make ShaDa code keep temporary file in-place for user to decide
what to do with it. Vim deletes temporary file in these cases.
returns something meaningful when used with
argument: in Vim
it used to return useless address of the string (strings are copied to the
newly allocated memory all over the place) and fail on types which cannot be
coerced to strings. See id()
for more details, currently it uses
always triggers when moving between windows.
:lua print("a\0b") will print
a^@b, like with
:echomsg "a\nb" . In Vim
b on separate lines, exactly like
:lua print("a\nb") .
:lua error('TEST') emits the error “E5105: Error while calling lua chunk:
[string "<VimL compiled string>"]:1: TEST”, whereas Vim emits only “TEST”.
Lua has direct access to Nvim API
does not warn about "No matching autocommands".
accepts a count.
does not show a prompt if the file was updated externally.
does not accept ex-flags
. With an arg it is equivalent to :lua=
The meanings of arrow keys do not change depending on 'wildoptions'
support for each other’s features (return on
cancel and completion respectively) via dictionary argument (replaces all
other arguments if used), and "cancelreturn" can have any type if passed in
support user-defined cmdline highlighting.
are lower priority than most other
highlights match under cursor instead of last match found
is low-priority unless foreground color is set
superseded by hl-WinSeparator
Highlight groups names are allowed to contain the characters
It is an error to define a highlight group with a name that doesn't match
Replay of a macro recorded during :lmap produces the same actions as when it
was recorded. In Vim if a macro is recorded while using :lmap'ped keys then
the behaviour during record and replay differs.
is implemented via :lmap instead of :lnoremap so that you can use
macros and 'keymap'
at the same time. This also means you can use :imap
the results of keys from 'keymap'
Creating a mapping for a simplifiable key (e.g.
<C-I>) doesn't replace an
existing mapping for its simplified form (e.g.
"#" followed by a digit doesn't stand for a function key at the start of the
lhs of a mapping.
avoids useless/phantom jumps.
syncolor.vim has been removed. Nvim now sets up default highlighting groups
automatically for both light and dark backgrounds, regardless of whether or
not syntax highlighting is enabled. This means that :syntax-on
are now identical. Users who previously used an
after/syntax/syncolor.vim file should transition that file into a
Working directory (Vim implemented some of these after Nvim):
checks for tab-local directory if and only if -1 is passed as
window number, and its only possible returns values are 0 and 1.
getcwd(-1) is equivalent to
getcwd(-1, 0) instead of returning the global
working directory. Use
getcwd(-1, -1) to get the global working directory.
Missing legacy features nvim-missing
These legacy Vim features are not yet implemented:
Removed legacy features nvim-removed
These Vim features were intentionally removed from Nvim.
ex (alias for "nvim -e")
exim (alias for "nvim -E")
view (alias for "nvim -R")
vimdiff (alias for "nvim -d" diff-mode
:mode (no longer accepts an argument)
:scriptversion (always version 1)
:sleep! (does not hide the cursor; same as :sleep)
Emacs tags support
X11 integration (see x11-selection
are unnecessary because Nvim
For example, to mimic Vim's StatusLineTerm:
hi StatusLineTerm ctermfg=black ctermbg=green
hi StatusLineTermNC ctermfg=green
autocmd TermOpen,WinEnter * if &buftype=='terminal'
(Nvim is always "nocompatible".)
(gjkHw<*- and all POSIX flags were removed)
(Vim encryption implementation)
("utf-8" is always used)
"t" flag was removed
(Nvim uses pipes and PTYs consistently on all platforms.)
(Names of builtin highlight-groups
cannot be changed.)
Use the following script to emulate 'insertmode'
autocmd BufWinEnter * startinsert
inoremap <Esc> <C-X><C-Z><C-]>
inoremap <C-C> <C-X><C-Z>
inoremap <C-L> <C-X><C-Z><C-]><Esc>
inoremap <C-Z> <C-X><C-Z><Cmd>suspend<CR>
noremap <C-C> <Esc>
snoremap <C-C> <Esc>
noremap <C-\><C-G> <C-\><C-N><Cmd>startinsert<CR>
cnoremap <C-\><C-G> <C-\><C-N><Cmd>startinsert<CR>
inoremap <C-\><C-G> <C-X><C-Z>
autocmd CmdWinEnter * noremap <buffer> <C-C> <C-C>
autocmd CmdWinEnter * inoremap <buffer> <C-C> <C-C>
lua << EOF
if c == '\27' then
local mode = vim.api.nvim_get_mode().mode
if mode:find('^[nvV\22sS\19]') and vim.fn.getcmdtype() == '' then
Nvim always displays up to 6 combining characters. You can still edit
text with more than 6 combining characters, you just can't see them.
. See mbyte-combining
Nvim delegates memory-management to the OS.
Nvim delegates memory-management to the OS.
Everything is allowed in 'exrc'
files since they must be explicitly marked
(Vim 7.4.852 also removed this for Windows)
(Add "s" to 'shortmess'
Folds are not updated during insert-mode.
: Nvim Lua
API is not compatible with Vim's "if_lua".
are not supported.
--literal (file args are always literal; to expand wildcards on Windows, use
nvim +"n *"
Easy mode: eview, evim, nvim -y
Restricted mode: rview, rvim, nvim -Z
Vi mode: nvim -v
Nvim does not have special
keycodes to configure
terminal capabilities. Instead Nvim treats the terminal as any other UI,
sets the terminal cursor style if possible.
Xterm can be run in a mode where it uses true 8-bit CSI. Supporting this
requires autodetection of whether the terminal is in UTF-8 mode or non-UTF-8
mode, as the 8-bit CSI character has to be written differently in each case.
Vim issues a "request version" sequence to the terminal at startup and looks
at how the terminal is sending CSI. Nvim does not issue such a sequence and
always uses 7-bit control sequences.
Cscope support has been removed in favour of LSP based solutions.
was removed. Instead, use
and print the resulting HTML
using a web browser or some other HTML viewer.