Following HEAD

Björn Linse edited this page Nov 18, 2018 · 74 revisions

The following changes may require users to update configuration, plugins, or expectations. Only breaking changes are mentioned here, this is not a reference for new features (see :help nvim instead).


The Python package neovim was renamed to pynvim.

"Neovim" can mean a lot of things. It can relate to the editor, or the project, or (prior to this change) the Python module, or the Ruby gem, etc. Especially confusing was the fact that the Python side would refer to it as neovim whereas the Neovim side referred to it as python-client. Now, both sides call it pynvim for the greater good.

For the time being, neovim acts as a transitional package for the new pynvim. Unfortunately, due to limitations in pip, the neovim package cannot be safely upgraded with pip install --upgrade neovim on all systems. The safest path to upgrade is

pip uninstall neovim
pip uninstall pynvim # only if you tried to upgrade already and it failed
pip install pynvim

At this point, it is safe to pip install neovim again, if any third-party package has it as a formal dependency. Otherwise it shouldn't be necessary.

import neovim is still supported, both in plugins and third-party software using it as a library. If import neovim fails, then the upgrade wasn't successful. Follow the instructions above.


The meaning of the --embed and --headless flags changed to facilitate better startup behaviour with external UIs. An UI embedder (any user of nvim_ui_attach) should start nvim using nvim --embed but without --headless. An embedder not using the UI protocol should use nvim --embed --headless.

With --embed only, nvim will wait for the embedding process to call nvim_ui_attach before sourcing startup files and reading buffers. This is so that UI can show startup messages and possible swap file dialog for the first loaded file. The process can do requests before the nvim_ui_attach, for instance a nvim_get_api_info call so that UI features can be safely detected by the UI before attaching. However requests before attach (just like --cmd commands) cannot access init.vim configuration.

For many UI embedders, this will improve startup behavior automatically, by supporting startup messages and swap files prompts. But it could be a potentially breaking change for other use cases of --embed. These can use nvim --embed --headless which will replicate the old behavior of embed on master and later releases, and still work with older versions of nvim.

For an UI that wants to do additional initialization after init.vim the following pattern can be used: Before nvim_ui_attach send a singlenvim_command request with the command "autocmd VimEnter * call rpcrequest(1, 'vimenter')". In the vimenter method handler the UI can then safely execute any requests, and nvim will only enter normal mode when this handler returns.


Changes from #7679:

  • Nvim treats a stdin stream as text by default:
    echo foo | nvim
    • To get the old behavior, pass stdin to -s:
      echo foo | nvim -s -
  • Windows only: nvim *.txt (glob/wildcard expression) is treated literally. Use the :next (:n) command instead:
    nvim +"n *.txt"


Default fillchars for 'vert' and 'sep' changed from respectively | and - to and · when the ambiwidth setting is different from double, else old defaults apply. #8035


VimL (Vimscript) compatibility: count is no longer an alias to v:count. This helps avoid mistakes in scripts. #7407


:terminal now starts in normal mode (#6808), like any other buffer, instead of terminal mode. This avoids the cursor getting "trapped" when a terminal is started.


The highlight option is now read-only (#6737), so that the built-in highlight groups (and their behaviors) are predictable and can be used as keys for features like winhighlight.


Lua support (#4411) has been merged. This means that Lua is always available for scripting, but also means that nvim now requires either Lua or LuaJIT at runtime. LuaJIT is the default, but one can build against Lua instead by passing -DPREFER_LUA=ON to cmake.


Default 'mouse' setting changed from mouse=a to mouse= (empty). This will change again in the future after mouse=a is improved. To continue using mouse, add this to your init.vim:

set mouse=a


Support for $NVIM_TUI_ENABLE_CURSOR_SHAPE was removed. Use the guicursor option to control cursor styling. See FAQ.

  • To disable cursor style changes, set guicursor to empty:
    :set guicursor=
  • Note: guicursor is enabled by default only if Nvim is certain it won't cause problems on your terminal. If you know that cursor shaping works on your terminal, set guicursor in your init.vim:
    :set guicursor=n-v-c:block-Cursor/lCursor-blinkon0,i-ci:ver25-Cursor/lCursor,r-cr:hor20-Cursor/lCursor


#5529 merged Vim's support for "partial functions" which made Nvim more strict about when the implicit self variable is available. Functions that reference self (which is common with job callbacks) must either be declared as dict functions:

function! s:on_stdout(id, data, event) dict abort

or as part of the job options dictionary:

let s:opts = { ... }
function! s:opts.on_stdout(id, data, event) abort

Job callbacks also must have at least 3 parameters now. See


'encoding' cannot be changed to a value other than "utf-8", even during initialization. #2905

(Background: #2929 restricted 'encoding' to be modifiable only during initialization. One year later, we've found no problems with UTF-8 as the internal encoding, and are now making this mandatory. This only affects the internals of Nvim, it doesn't affect file encodings or plugins.)


:oldfiles! was removed in favor of restoring Vim's :browse oldfiles behavior. #5214


The :Man command is enabled by default (PR #4449), you no longer need

runtime! ftplugin/man.vim

in your vimrc.


"True color" support now requires set termguicolors in your init.vim. NVIM_TUI_ENABLE_TRUE_COLOR is ignored. #4690


:filetype plugin indent on and :syntax on are now executed by default after your vimrc.

  • If your vimrc calls :filetype, Neovim will not change your preference.
  • If your vimrc calls :filetype off or :syntax off, that will be respected.
  • If filetype plugin indent on and/or syntax on is in your vimrc, you can delete those lines.

See :help startup for complete details.


The DECSCUSR sequence is now sent "unwrapped" to the terminal; this affects tmux users in that cursor style changes are now localized to a tmux pane instead of being global to the parent terminal.

Depending on your terminal this may make break cursor style changes; if that happens then see NVIM_TUI_ENABLE_CURSOR_SHAPE in the nvim manual (man 1 nvim).

See #3165 for more information.


The NVIM_TUI_ENABLE_TRUE_COLOR environment variable no longer sets has('gui_running'). This means some (broken) colorschemes might look weird until they're fixed, but more importantly it also means that various plugins that make decisions based on the result of has('gui_running') will not be misled into thinking the user is running outside of a terminal.

Note: jellybeans and this molokai fork are known to work with true color even after the change . Colorschemes that don't work after this change should be fixed (they should set ctermfg/ctermbg and guifg/guibg, without checking has('gui_running'))

See #4155 for more information.


The 'swapsync' option has been removed. Swap files are now always fsync(2)'d after writing them.

See #4009 for more information.


You might notice that :version reports v0.1.2-... instead of v0.1.1-.... This does not mean v0.1.2 was released, but that the version now better conforms to

See #3839 for more information.


The Getscript plugin has been removed, so the commands GLVS, GetLatestVimScripts, and GetScripts are no longer supported. Getscript users should consider migrating to a 3rd party plugin manager, such as vim-plug.

See #2231 and #3826 for more information.


The -X command-line flag, which was a no-op, has been removed.

See #3641 for more information.


The open command has been removed. It works the same as visual, so use that instead.

See #3569 for more information.


Neovim now supports XDG configuration. The default config paths changed, so ~/.nvimrc and ~/.nvim/ will not be found by default. See :help nvim-from-vim for quick migration steps.


  • Default user config directory is now ~/.config/nvim/
  • Default "vimrc" location is now ~/.config/nvim/init.vim


The 'viminfo' option is now an alias for 'shada'. 'viminfo' can no longer include n and it can no longer be shared with Vim.

See #3469 for more information.


The 'encoding' option can no longer be changed after initialization.

See #2929 for more information.


The behavior of the mkdir() function has changed:

  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 the octal permissions 0700. Vim's mkdir() will create /tmp/foo with 0755.
  2. If you try to create an existing directory with 'p', such as with mkdir('/', 'p')), mkdir() will silently fail. In Vim this was an error.
  3. Upon failure, mkdir() related error messages now include strerror() text.

See #3041 for more information.


The Print command has been removed. It works the same as print, so use that instead.

See #3049 for more information.


The default value for the 'history' option has changed from 50 to 10000. To emulate the old behavior, add the following to your nvimrc:

set history=50

See #2868 and #2676 for more information.


The POSIX 'cpoptions' flags have been removed. The VIM_POSIX environment variable now has no effect.

Attempting to add any of the following flags to 'cpoptions' will trigger an error: \ . / & | { #

See #2943 for more information.


The tearoff command has been removed. It was never actually implemented, so the only functional difference should be that


now returns 0 instead of 2.

See #3003 and #3007 for more information.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.