Vimspector: a debugger that keeps its configuration in a .vimspector.json file next to the code
vimspector - A multi-language debugging system for Vim
At a glance
- What is it?
- Vimspector turns Vim into a graphical debugger by driving language specific debug adapters from a configuration file committed alongside the source. It is a good fit for C, C++, Python and Java developers who want breakpoints, watch expressions and a debug console without leaving the editor, and a poor fit for anyone who needs a built-in visual layout pane.
- Who is it for?
- Adopt Vimspector if you already live in Vim, work in C, C++, Python, TCL or Java, and want a checked in debug configuration you can share with the rest of a team. Skip it if you need an integrated layout view, if your language has no working debug adapter on your platform, or if you are on Neovim and want native DAP behaviour.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 5 days ago.
- What is it written in?
- Mainly Vim Script, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- puremourning/vimspector4,326 ★ · +2
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| puremourning/vimspector | 4.3k | 4.3k |
2 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Where the debugger lives: an adapter process, not Vimscript
Vimspector is not a debugger written in Vimscript. It is a front end that starts a separate debug adapter program, talks to it over the Debug Adapter Protocol, and draws the adapter's replies in Vim buffers. That distinction decides almost everything about how it feels to use.
Every capability listed in the README's feature list exists because some adapter answers the request. Breakpoints, step in, out, over and up, run to cursor, watch expressions with autocompletion, an interactive console, a hex dump of process memory: each one is a protocol call rather than a reimplementation of debugging logic.
The audience is specific. Developers who work in a language VS Code can debug, who already keep their editor configuration in dotfiles, and who want their debug setup versioned with the code. The `.vimspector.json` file at the repository root is the giveaway: this is aimed at teams, because the configuration can be committed to source control. The plugin is written mostly in Vim Script, with Python 3 components in the python3/ directory.
Installing the plugin and getting a first session running
The README points to two installation paths: a repository clone installed through Vim's package mechanism with select gadgets, and installation through a plugin manager. The tutorial and usage overview live on the Vimspector website rather than in the README, and the project's own reference guide covers the `.vimspector.json` format in detail.
Debug adapters are installed separately as gadgets: the README's table of contents covers the VimspectorInstall and VimspectorUpdate commands, install_gadget.py and manual gadget installation.
The repository also ships its own developer checks. The Makefile runs a Python linter over the python3/ directory and the top level scripts, then a Vim script linter across the autoload, compiler, plugin, tests and syntax directories:
flake8 python3/ *.pyThat target is for contributors, not users, but it shows the shape of the project: Vim plugin code on one side, Python on the other, and a JSON schema in docs/schema that drives generated documentation through the update-schema-docs script.
What the .vimspector.json profile actually controls
The configuration file is the mechanism worth understanding, because it is where most surprises live. The feature list calls it a flexible configuration syntax that can be checked in to source control, and the reference guide documents the format in detail.
Two features in that file stand out. The first is pre-launch build strategies, which lets a debug session compile before it attaches, so a build command and a launch command are coupled in one place rather than in a shell script you have to remember. The second is the remote launch and attach configuration for C++ and Python.
Customisation follows the same pattern. Default signs, sign priority so two plugins do not fight over the breakpoint column, presentation hints, WinBar sizing, window sizes, and the terminal size the adapter sees are all configuration, not code changes. The one thing this file cannot do is express a language the adapter does not implement, which is where the project's scope ends.
Language coverage is real for three, theoretical for the rest
The README states that Vimspector is mostly tested for C++, Python and TCL, and that in theory it supports any language VS Code supports. Read that second clause as a statement about protocol compatibility, not about testing. An adapter that speaks the protocol will be driven, but nothing in the project guarantees that its variable presentation, its restart semantics or its remote attach options map cleanly onto Vimspector's windows.
Dedicated sections exist for C, C++, Rust, Jai, Python, TCL, C#, Go, PHP, JavaScript and TypeScript, Java and Lua, with language specific notes such as pretty printing for C data structures, hot code replace for Java, and combined use with YouCompleteMe. Those sections are where the real difference lies. A language with a section has been thought about; a language without one is an experiment.
Two named boundaries are worth keeping in mind. Neovim has documented limitations, listed as its own heading in the README, so behaviour under Neovim is not identical to Vim. Windows has documented differences too. Read those sections before committing a workflow on either platform.
Five kinds of breakpoint, and the window that lists them
Breakpoints in Vimspector are not one feature but several, and the difference matters when a launch fails. There are function, line and exception breakpoints, conditional breakpoints for functions and for lines, logpoints that print instead of stopping, data breakpoints on a memory location, and instruction breakpoints for stepping at the assembly level.
Each kind becomes a different protocol request, so an adapter decides what it can honour.
The README also documents saving and restoring breakpoints.
Where Vimspector falls short of a visual IDE debugger
Vimspector has a section titled what Vimspector is not, and it also has a status section that marks parts of the feature set as experimental. That is an unusual admission to find in a README, and it is the honest signal here: the project distinguishes what it supports from what it merely allows.
The concrete gap is the layout pane. VS Code and other IDE debuggers allocate a fixed region for frames, variables, watch and console, and that region does not move when you scroll. Vimspector builds its interface from Vim windows, buffers and signs, so the reader ends up managing window sizes, the WinBar, and which buffer is focused. The configuration options for window sizes and WinBar exist precisely because this is not free.
The second gap is remote debugging cost. Launch and attach by PID, a PID picker, remote launch and remote attach, and multi process debugging all work through adapters, so the remote side needs its own adapter, its own configuration and its own network path. A team debugging a container or a board will spend its time on that plumbing rather than on the breakpoint.
The third gap is the adapter install itself. Debug adapters are separate gadgets, installed through the VimspectorInstall and VimspectorUpdate commands, install_gadget.py, or by hand.
Vimspector against nvim-dap and Vim termdebug
The meaningful comparison is with nvim-dap and with Vim's own termdebug, because they take a different approach rather than a different quality level.
nvim-dap implements the client side of the Debug Adapter Protocol natively inside Neovim's Lua runtime. Its configuration is Lua code evaluated at runtime, so profiles can be computed, conditioned on the current file, or assembled from shared modules. Vimspector writes a JSON file instead. JSON can be committed to a repository and diffed, which suits a team that wants one shared debug setup.
Vim termdebug drives gdb directly. It ships with Vim, needs no adapter, no JSON and no configuration file, and gives an inferior experience for Python, Java, JavaScript or anything gdb cannot attach to. Vimspector covers those languages; termdebug does not. If your work is C or C++ on a machine with gdb, termdebug is the cheaper answer.
So the choice is not about debugging quality. It is about whether you want a versionable configuration file driving many adapters, native protocol code in Lua, or gdb's own interface with no dependencies.
Editorial conclusion
Adopt Vimspector if you already live in Vim, work in C, C++, Python, TCL or Java, and want a checked in debug configuration you can share with the rest of a team. Skip it if you need an integrated layout view, if your language has no working debug adapter on your platform, or if you are on Neovim and want native DAP behaviour. Before committing a profile, verify that the gadget for your language installs and starts on your machine.
Frequently asked questions
How do I use Vimspector?
Install the plugin through a repository clone with Vim packages or through a plugin manager, then create a `.vimspector.json` profile that names the adapter and the program to launch. The plugin starts the adapter and opens its breakpoints, stack, watch, console and output windows inside Vim.
Which languages does Vimspector debug?
It is mostly tested for C++, Python and TCL, and the configuration sections cover C, Rust, Jai, C#, Go, PHP, JavaScript, TypeScript, Java and Lua. In theory any language VS Code supports works through its debug adapter, though the README marks the wider claim as theory rather than tested behaviour.
Do I need to install a debug adapter separately for Vimspector?
Vimspector starts a debug adapter program and communicates with it over the Debug Adapter Protocol, so the adapter for your language has to exist on the machine. The README documents installing these adapters, which it calls gadgets, through the VimspectorInstall and VimspectorUpdate commands, install_gadget.py, or manual gadget installation.
Does Vimspector support conditional breakpoints and logpoints?
Yes. The feature list includes conditional breakpoints for functions and lines, logpoints, exception breakpoints, data breakpoints and instruction breakpoints. Which of these an adapter honours depends on the language, since each one is sent as a distinct protocol request.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/puremourning-vimspector)Star history chart for your README
[](https://hysenlabs.com/projects/puremourning-vimspector)Was this useful?