Vimspector: a multi-language graphical debugger inside Vim

The gap Vimspector fills for Vim users

Vim has never shipped a general-purpose graphical debugger. The traditional route is a terminal debugger such as GDB or pdb in a split, where you type commands and read text output. Vimspector takes a different route: it speaks the Debug Adapter Protocol, the same protocol Visual Studio Code uses, and renders the results in Vim windows. That means breakpoints appear as signs in the gutter, locals and globals sit in their own pane, and stepping is bound to keys rather than typed as commands.

The project is explicit about its target. The README says the plugin is "mostly tested for C++, Python and TCL", while claiming theoretical support for any language Visual Studio Code supports. That sentence is the honest summary of the trade-off: the protocol is general, but the tested surface is narrower. If you debug C++ or Python daily and want to stay in Vim, you are the intended user. If you debug something exotic, you are on the theoretical side of that sentence.

How the Debug Adapter Protocol reaches your editor

Vimspector is a client. It does not implement a debugger engine for each language. Instead it launches or attaches to a debug adapter, a separate process that understands one language, and exchanges DAP messages with it over a pipe. The adapter does the actual work: it talks to GDB, LLDB, debugpy or whatever backend it wraps, and reports variables, stack frames and program output back to Vimspector.

Those adapters are what the project calls gadgets. The repository ships install_gadget.py and the VimspectorInstall command to fetch them, and the README documents a gadget directory where they live. This split explains most of the setup friction: installing the plugin gives you the client, not the debuggers. It also explains the configuration format. A .vimspector.json file describes which adapter to start, how to launch or attach to your program, and which arguments to pass. Because that file is plain JSON, the README notes it can be checked in to source control, so a team can share debug profiles alongside the code they debug.

Installing Vimspector and debugging a first script

The README offers two installation routes: a repository clone placed under a Vim packages directory, or a plugin manager. Both paths are documented in the plugin's Installation section, and both leave you with the same next step, which is installing gadgets. The VimspectorInstall command is the documented way to do that, and the README's table of contents lists it alongside VimspectorUpdate as the pair of commands for gadget management. The README does not print a gadget name in that section, so pass the name of the adapter you want from the installer's list rather than copying one from here. The README also documents install_gadget.py as a standalone script for the same job outside Vim.

With an adapter in place you need a launch configuration. Vimspector reads .vimspector.json from the project. The README points to the reference guide for the full format, and the repository keeps its own .vimspector.json at the top level, so the file is real rather than hypothetical. The README does not print a complete minimal configuration, so the reference guide is the place to get the exact keys for your adapter.

Once that file exists, Vimspector offers configuration selection and the mappings documented in the README start a session. The README lists launch and attach, including a PID picker for attaching to a running process, and a human-mode mapping set for people who do not want the Visual Studio key bindings.

Where Vimspector stops being the right tool

The most concrete limitation is the one the README states itself. Support beyond the tested languages is theoretical, and the README warns about caveats rather than promising parity with Visual Studio Code. A language with no gadget in the installer is a language you wire up manually, and the README has a section titled Manual gadget installation for exactly that case. That is real work, not a flag.

Neovim is a second boundary. The README carries a dedicated Neovim limitations section, which tells you the plugin's behaviour there differs from Vim in ways the project considered worth documenting separately. Windows gets its own differences section too. If you are on Neovim or Windows, read those before assuming the tutorial screenshots apply to you.

The third boundary is the configuration file. Vimspector does not infer how to launch your program. You write the adapter name, the request type and the arguments. Get the program path or the working directory wrong and the session fails to start with an adapter error rather than a helpful guess. Projects with unusual launch procedures, wrappers, environment setup or container entrypoints will spend time in that JSON.

Vimspector against Vim's built-in termdebug and Neovim's DAP clients

The closest built-in alternative is termdebug, which ships with Vim and drives GDB in a terminal window with some Vim integration. The difference is architectural. termdebug is GDB-only and terminal-oriented; Vimspector is protocol-oriented, so the same UI works for Python through debugpy, for Java through its adapter, and for the other languages the installer covers. If you only ever debug C and C++ with GDB, termdebug asks for nothing beyond the Vim you already have, while Vimspector asks for a plugin install plus a gadget plus a .vimspector.json. That extra setup buys language coverage and a graphical variable view, and it costs you the zero-configuration start.

On Neovim, the comparison people search for is against the DAP client plugins built for Neovim's Lua ecosystem. Those are separate projects with their own adapter management and their own UI conventions. Vimspector's approach is a Vim script and Python codebase that targets Vim first, with Neovim limitations documented. Choosing between them is largely choosing which editor you actually run, because the adapter ecosystem underneath is the same DAP idea.

Upgrades, the Apache-2.0 licence and what maintenance looks like

The repository is not archived, and the last push was on 2026-09-22. The most recent releases listed are builds from 2024-05-06, so the release cadence and the commit cadence are not the same thing; if you pin to a tagged build, check what has landed on master since. Upgrading the plugin itself is the ordinary plugin-manager path, but gadgets are separate artefacts. The README documents VimspectorUpdate for that, and the Makefile shows the project building its own CI and manual test containers under the containers target, which is how the maintainers exercise the plugin rather than something you run to use it.

The licence is Apache-2.0, and the repository carries a LICENCE file at the top level. Apache-2.0 is a permissive licence with an explicit patent grant, which matters if you vendor the plugin into a corporate toolchain. The gadgets it installs are not covered by that licence; they are separate debug adapters from separate projects, each with its own terms. That distinction is worth checking before you ship a bundled environment, and it is a question for your own legal review rather than something the README answers.

Editorial conclusion

Adopt Vimspector if you already live in Vim and want breakpoints, watches and a disassembly view without switching to an IDE, and if you are willing to install a debug adapter for each language you use. Skip it if you want a debugger that works the moment the plugin loads, or if you depend on a language whose adapter the project does not ship. Before committing, verify that VimspectorInstall pulls the gadget for your language, that the .vimspector.json you write matches the script you actually run, and that your Vim build has the terminal and job features the plugin needs.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. puremourning/vimspector on GitHub
4. README
5. Releases