Guide · Open source

How to use Vim in VS Code with VSCodeVim: setup and key remapping

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

VSCodeVim is an open-source extension that makes Visual Studio Code behave like the Vim text editor, so you can edit text with Vim's keyboard commands and modes. This guide is for people who already know Vim and want those habits inside VS Code. After reading it, you will know how to install the extension, set a few important options, remap keys, and load parts of an existing .vimrc.

VSCodeVimVSCodeVim/Vim · ★ 15.2k · MIT Install options & downloads

Quick start

1Install the extension. Install VSCodeVim from the VS Code Marketplace or OpenVSX Marketplace in Visual Studio Code.
2Fix macOS key repeat. On Mac, run the defaults command for your editor, then log out, log back in and restart VS Code.
3Open settings.json. Open your VS Code settings.json file to add VSCodeVim options.
4Set core options. Add settings such as vim.incsearch, vim.hlsearch, vim.useSystemClipboard and vim.leader.
5Add key remappings. Add binding lists such as vim.insertModeKeyBindings to remap keys for each mode.
6Load a .vimrc if needed. If you have an existing .vimrc, load the parts VSCodeVim supports.

Install VSCodeVim in Visual Studio Code

VSCodeVim can be installed from the VS Code Marketplace or the OpenVSX Marketplace. You need Visual Studio Code installed first.

The README lists no separate install commands, so installation is done through the extension view in VS Code.

Open Visual Studio Code.
Search for the VSCodeVim extension in the extensions view and install it.
Use the Marketplace listing or the OpenVSX listing, whichever you can access.

Fix key repeat on macOS

On Mac, the README says you should disable the press-and-hold behaviour so that holding a key repeats it. Run the command for your editor in Terminal, log out and back in, then restart VS Code.

The README also recommends increasing the Key Repeat and Delay Until Repeat settings under the Keyboard settings in macOS.

defaults write com.microsoft.VSCode ApplePressAndHoldEnabled -bool false

Understand Windows control key behaviour

Like real Vim, VSCodeVim takes over your control keys. You can adjust this with the useCtrlKeys and handleKeys settings, which let you hand specific keys back to VS Code.

vim.useCtrlKeys: controls whether Vim takes Ctrl key combinations.
vim.handleKeys: delegates configured keys to VS Code instead of VSCodeVim.

Configure VSCodeVim in settings.json

VSCodeVim reads its options from settings.json. The README gives a quick example with settings for easymotion, incremental search, system clipboard, highlighted search, and a leader key.

The README notes that the documented settings are only a subset. The full list is on the extension's Settings tab in the extensions view.

vim.incsearch and vim.hlsearch control search behaviour.
vim.useSystemClipboard uses the system clipboard.
vim.leader sets the leader key, for example to space.

{
  "vim.incsearch": true,
  "vim.useSystemClipboard": true,
  "vim.hlsearch": true,
  "vim.leader": "<space>"
}

Remap keys with keybinding settings

You can remap keys by adding binding lists to settings.json. The README describes separate lists for insert, normal, visual and operator-pending modes, plus NonRecursive variants. The example maps jj to Escape in insert mode.

The README also covers debugging remappings and more complex key combinations, which you can read in its Key Remapping section.

vim.insertModeKeyBindings: remaps keys in insert mode.
vim.normalModeKeyBindingsNonRecursive: remaps keys in normal mode without recursion.

"vim.insertModeKeyBindings": [
  {
    "before": ["j", "j"],
    "after": ["<Esc>"]
  }
]

Load parts of an existing .vimrc

VSCodeVim supports a .vimrc file, so you can load parts of an existing Vim configuration into VS Code. The README does not list every supported line, so check the project's documentation for details on which parts are handled.

Because VSCodeVim is an emulator, some settings and plugins may behave differently from real Vim.

What people use it for

Editing code in VS Code with Vim motions and modes, such as moving and changing text from the keyboard.
Remapping a key like jj to Escape in insert mode through settings.json.
Setting a leader key and custom normal mode bindings for common actions.
Reusing parts of an existing .vimrc in VS Code.
Using the system clipboard with Vim-style yank and paste.

Frequently asked questions

Is VSCodeVim free?

The project is licensed under the MIT licence, which is an open-source licence. The README does not list prices, so check the extension listing for any cost details.

What do I need to install VSCodeVim?

The README lists Visual Studio Code as the prerequisite. You install the extension from the Marketplace or OpenVSX.

Is VSCodeVim the same as real Vim?

No. The README calls VSCodeVim a Vim emulator, and it lists some plugin emulations rather than the full set of Vim features.

How do I remap keys in VSCodeVim?

Add binding lists such as vim.insertModeKeyBindings or vim.normalModeKeyBindingsNonRecursive to settings.json. Each entry has a before key sequence and an after sequence or command.

Why do keys repeat badly on Mac?

On Mac, the README says press-and-hold can block key repeat. Disable ApplePressAndHoldEnabled with the defaults command for your editor, then restart VS Code.

What are alternatives to VSCodeVim?

The project lists Neovim, Vim, IdeaVim and Vim Emulator for Atom as comparable projects. Choose based on which editor you use.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

VSCodeVim is a good choice if you already know Vim and want its keys inside Visual Studio Code, especially with settings.json remapping. If you have never used Vim, or you need full Vim feature parity, the README suggests picking a simpler editor or running real Vim or Neovim instead.

Install options & downloads