getting started - theol0403/vscode-neovim GitHub Wiki

Table of Contents

Installation

  • Install the vscode-neovim extension.
  • Install Neovim 0.5.0 or greater.
    • Set the neovim path in the extension settings. You must specify full path to neovim, like "C:\Neovim\bin\nvim.exe" or "/usr/local/bin/nvim".
    • The setting id is "vscode-neovim.neovimExecutablePaths.win32/linux/darwin", respective to your system.
  • If you want to use neovim from WSL, set the useWSL configuration toggle and specify linux path to nvim binary. wsl.exe windows binary and wslpath linux binary are required for this. wslpath must be available through $PATH linux env setting. Use wsl --list to check for the correct default linux distribution.

Neovim configuration

Since many vim plugins can cause issues in vscode, it is recommended to start from an empty init.vim. For a comprehensive guide for which types of plugins are supported, see this

Before creating an issue on github, make sure you can reproduce the problem with an empty init.vim and no vscode extensions.

To determine if neovim is running in vscode, add to your init.vim:

if exists('g:vscode')
    " VSCode extension
else
    " ordinary neovim
endif

To conditionally activate plugins, vim-plug has a few solutions. For example, using the Cond helper, you can conditionally activate installed plugins (source):

" inside plug#begin:
" use normal easymotion when in vim mode
Plug 'easymotion/vim-easymotion', Cond(!exists('g:vscode'))
" use vscode easymotion when in vscode mode
Plug 'asvetliakov/vim-easymotion', Cond(exists('g:vscode'), { 'as': 'vsc-easymotion' })

See plugins for tips on configuring vim plugins.

VSCode configuration

See tips for information regarding recommended VSCode configuration.

See bindings for a list of default VSCode bindings and commands.

  • The extension works best if editor.scrollBeyondLastLine is disabled.
  • To have the explorer keybindings work, you will need to set "workbench.list.automaticKeyboardNavigation": false. Note that this will disable the filtering in the explorer that occurs when you usually start typing.
  • On a Mac, the h, j, k and l movement keys may not repeat when held, to fix this open Terminal and execute the following command: defaults write com.microsoft.VSCode ApplePressAndHoldEnabled -bool false.

Custom keybindings

Every keyboard shortcut that gets sent to neovim must be explicitly defined in vscode. By default, only bindings that are included by neovim by default are sent.

To pass custom bindings to neovim, for example C-h in normal mode, add to your keybindings.json:

{
    "command": "vscode-neovim.send",
    // the key sequence to activate the binding
    "key": "ctrl+h",
    // don't activate during insert mode
    "when": "editorTextFocus && neovim.mode != insert",
    // the input to send to neovim
    "args": "<C-h>"
}

To disable an existing shortcut, for example C-a, add to your keybindings.json:

{
    "command": "-vscode-neovim.send",
    "key": "ctrl+a"
}

The vscode keybindings editor provides a good way to delete keybindings.

VSCode specific differences

  • File and editor management commands such as :e/:w/:q/:vsplit/:tabnext/etc are mapped to corresponding vscode commands and behavior may be different (see below). Do not use vim commands like :w in scripts/keybindings, they won't work. If you're using them in some custom commands/mappings, you might need to rebind them to call vscode commands from neovim with VSCodeCall/VSCodeNotify (see below).
  • Visual modes don't produce vscode selections, so any vscode commands expecting selection won't work. To round the corners, invoking the VSCode command picker from visual mode through the default hotkeys (f1/ctrl/cmd+shift+p) converts vim selection to real vscode selection. This conversion is also done automatically for some commands like commenting and formatting. If you're using some custom mapping for calling vscode commands that depends on real vscode selection, you can use VSCodeNotifyRange/VSCodeNotifyRangePos/VSCodeNotifyVisual (linewise, characterwise, and automatic) which will convert vim visual mode selection to vscode selection before calling the command (see below).
  • When you type some commands they may be substituted for the another, like :write will be replaced by :Write.
  • Scrolling is done by VSCode. C-d/C-u/etc are slightly different.
  • Editor customization (relative line number, scrolloff, etc) is handled by VSCode.
  • Dot-repeat (.) is slightly different - moving the cursor within a change range won't break the repeat. sequence. In neovim, if you type abc<cursor> in insert mode, then move cursor to a<cursor>bc and type 1 here the repeat sequence would be 1. However in vscode it would be a1bc. Another difference is that when you delete some text in insert mode, dot repeat only works from right-to-left, meaning it will treat Del key as BS keys when running dot repeat.
⚠️ **GitHub.com Fallback** ⚠️