vscode-neovim: running a real Neovim inside VS Code

The problem vscode-neovim solves: emulation versus a real Neovim process

Most Vim support in VS Code is an emulator. It reimplements motions, operators and text objects in TypeScript and hopes to match Vim's behaviour closely enough that your fingers do not notice. vscode-neovim takes the other route. The README describes it as using "a fully embedded Neovim instance, no more half-complete Vim emulation", with Neovim running as the backend and VS Code handling insert mode and its own commands.

That distinction decides who the extension is for. If you have spent years accumulating a Neovim configuration, custom mappings, and plugin behaviour you rely on, an emulator will never reproduce it. If you only want hjkl and a few text objects in a stock VS Code install, pulling in a Neovim binary is extra machinery you do not need. The audience here is people who already run Neovim and want VS Code's editor features without giving up the modal editing layer they have tuned.

The extension's stated position is that VSCode's native functionality is used for insert mode and VSCode commands, "making the best use of both editors". That is a design claim worth reading literally: normal mode is Neovim's, insert mode is VS Code's.

How the Neovim backend and VS Code frontend divide the work

The split is the whole architecture. Neovim owns normal mode, so motions, operators, registers and your mappings execute in a real Neovim process. VS Code owns insert mode, so typing, autocompletion, snippets, LSP responses and multi-cursor editing go through the editor you already have configured. The README lists "First-class and lag-free insert mode" and "Complete integration with VSCode features (lsp/autocompletion/snippets/multi-cursor/etc)" as the payoff for that arrangement.

The consequence is that Neovim's own UI is not what you see. The extension exposes a Lua API so your configuration can reach back into VS Code: vscode.action, vscode.call, vscode.on, vscode.has_config, vscode.get_config, vscode.update_config, vscode.notify, vscode.eval, vscode.eval_async and vscode.with_insert, plus builtin module overrides and a VimScript equivalent. These are the hooks that let a Neovim-side mapping trigger a VS Code command rather than a Neovim one.

File and editor commands are the sharp edge of the split. The README states that commands such as :e, :q, :vsplit and :tabnext are mapped to corresponding VS Code commands and that behaviour may differ. It also warns directly that using Vim commands like :e in scripts/keybindings.ts will not work. If your muscle memory is built on those ex commands, expect friction rather than a drop-in replacement.

Installing vscode-neovim and writing a first init.lua

Installation has two halves, and both are mandatory. First install the vscode-neovim extension from the Visual Studio Marketplace, published as asvetliakov.vscode-neovim. Then install Neovim 0.10.0 or newer as a separate binary. The extension does not ship Neovim.

The README gives the manual path to the binary as optional but useful when nvim is not on your PATH. You must specify the full path, such as C:\Neovim\bin\nvim.exe or /usr/local/bin/nvim, and the setting name differs per platform: vscode-neovim.neovimExecutablePaths.win32, vscode-neovim.neovimExecutablePaths.linux or vscode-neovim.neovimExecutablePaths.darwin. The package.json confirms the default for each of those keys is the bare string nvim.

{
  "vscode-neovim.neovimExecutablePaths.linux": "/usr/local/bin/nvim"
}

Put that in your VS Code settings.json and reload the window. If the path is wrong, the extension has no backend to talk to, so check the output channel before assuming the extension itself is broken.

The README recommends starting from an empty init.vim, because many Vim plugins cause problems inside VS Code. Once the extension is running, the first useful thing to add is a guard so the same configuration file can serve both plain Neovim and the extension. In Lua:

if vim.g.vscode then
  -- VSCode extension
else
  -- ordinary Nvim
end

The README gives the equivalent VimScript form using exists('g:vscode'). Plugin managers have conditional loading for this: the README states that packer.nvim and lazy.nvim support cond = vim.g.vscode, that vim-plug has a few documented solutions, and that LazyVim ships a dedicated VSCode extra. Note the README's advice before filing an issue: reproduce the problem with an empty init.vim and no other VS Code extensions first.

Where vscode-neovim breaks: UI plugins, WSL paths and the empty-init rule

The most concrete limitation is stated in the extension's own feature list: feature-complete Vim integration applies "except insert-mode and some Nvim UI plugins". Telescope is the obvious casualty. A fuzzy finder that draws its own floating window needs Neovim's UI, and Neovim's UI is not what is on screen. The same logic applies to any plugin whose value is its rendering rather than its text manipulation.

The setup itself has failure modes. On Windows, using Neovim through WSL requires the useWSL toggle, a Linux path to the nvim binary, the wsl.exe Windows binary, and wslpath available through the Linux $PATH. The README suggests wsl --list to confirm the default distribution. Snap installs add another trap: the Neovim path must resolve to the snap binary location, which the README gives as possibly /snap/nvim/current/usr/bin/nvim, and you can check whether you are on a snap package by seeing whether which nvim resolves to /usr/bin/snap.

The empty-init rule is not just troubleshooting advice, it is a statement about how much of the plugin ecosystem is expected to work. The README says many Vim plugins can cause issues and recommends starting from an empty init.vim. If your configuration is a large curated set of Neovim plugins, the honest expectation is that you will spend time gating them behind vim.g.vscode rather than porting them wholesale. This is the wrong tool if you want your existing Neovim setup to appear unchanged inside VS Code.

vscode-neovim versus the VS Code Vim extension: emulation or a backend

The comparison people actually search for is vscode-neovim against the VS Code Vim extension. The difference is architectural, not a matter of polish. VS Code Vim is a reimplementation: it exists entirely inside VS Code, needs nothing installed alongside the editor, and therefore cannot run your init.lua or your Neovim plugins. vscode-neovim requires a Neovim binary of 0.10.0 or newer and treats it as the engine for normal mode.

That trade cuts both ways. The Vim extension wins on setup cost: one install, no binary, no path settings, no WSL plumbing. vscode-neovim wins on fidelity for anyone whose editing habits live in their Neovim config, which is why the README can claim custom init.lua support and most Nvim plugins. It also exposes the Lua API surface listed above, which has no equivalent in an emulator because there is no Neovim process to call from.

If you have never used Neovim, the emulator is the lower-risk choice. If you have a Neovim configuration you would rather not abandon, the extension's premise is exactly that configuration, and the cost is the binary dependency plus the plugin gating described above.

Maintenance, releases and what the MIT licence means here

The repository is not archived, and the last push was on 2026-09-21. Release cadence is visible in the published versions: v1.20.0 on 2026-09-18, v1.19.3 on 2026-09-11 and v1.19.2 on 2026-09-08. Whatever else that says, it does not describe a project that has gone quiet.

Upgrade cost is bounded by two declared requirements in package.json. The extension declares engines of node 22.x and vscode ^1.90.0, and the README requires Neovim 0.10.0 or newer. Those two version floors are what you check when something stops working after an update, because a mismatch on either side puts the extension outside its supported configuration. The release-please configuration files at the repository root indicate releases are automated from commit history, which matters if you track master rather than the Marketplace build.

The licence is MIT. For most users that is uneventful: you can use, modify and redistribute the extension, and the licence text in the LICENSE file governs. It is worth noting only if you plan to fork and ship the extension internally, at which point the usual MIT obligation to carry the copyright notice applies. That is a description of the licence, not legal advice; read the LICENSE file and talk to counsel if your organisation has rules about bundled dependencies.

Editorial conclusion

Adopt vscode-neovim if you already have a Neovim configuration you trust and want VS Code's LSP, snippets and multi-cursor behaviour to keep working underneath it; the extension is published on the Visual Studio Marketplace as asvetliakov.vscode-neovim and requires Neovim 0.10.0 or newer. Do not adopt it if your workflow depends on Neovim UI plugins such as telescope for file picking, because the README states that Nvim UI plugins are outside the supported set and file and editor commands such as :e and :q are remapped to VS Code commands instead. Before committing, verify three things on your own machine: that nvim resolves to 0.10.0 or newer, that the extension starts cleanly with an empty init.vim, and that any plugin you rely on is gated behind vim.g.vscode so it does not load inside VS Code.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. vscode-neovim/vscode-neovim on GitHub