nvim-dap: a Debug Adapter Protocol client that lives inside Neovim

The gap nvim-dap fills: DAP without leaving the terminal editor

Neovim has no built-in debugger. nvim-dap is a Debug Adapter Protocol client implementation for Neovim, which means it implements the editor side of the same protocol VS Code uses to talk to debug adapters. The plugin lets you launch an application to debug, attach to a running process, set breakpoints and step through code, and inspect application state.

The intended audience is narrow and clear: people who already work in Neovim and want breakpoint debugging there instead of switching to another editor for that one task. Everything the README lists as a goal points the same way. The stated goal is to "have a basic debugger in Neovim" and to double as a DAP client library so other plugins can build the interface on top. That second goal matters more than it sounds: nvim-dap is deliberately not a finished IDE debugger, it is the protocol layer plus a minimal set of commands, and the ecosystem supplies the rest.

How the protocol layer, widgets and REPL fit together

The architecture visible in the README is a client and a set of views over it. The client connects to a debug adapter, which is a separate process you install per language. The plugin itself does not ship adapters, and the README is explicit that debug adapter installations are out of scope: "It's not the business of an editor plugin to re-invent a package manager."

On top of that connection sit several ways to look at state. There is a built-in REPL opened with require'dap'.repl.open(), where you can type an expression and press ENTER to evaluate it, or use commands such as .help, .frames and .threads. Structured variables expand and collapse with ENTER on the corresponding line. There is also a widget UI, documented under :help dap-widgets, which the README suggests using ad hoc for values, threads and stacktraces, or wiring into permanent sidebars. Beyond that, UI extensions take over: nvim-dap-ui for an IDE-like layout, nvim-dap-view as a middle ground between that and the built-in widgets, and nvim-dap-virtual-text for inline values.

That layering is the design decision worth noticing. The core keeps the protocol and the commands; layout, panels and inline rendering are optional plugins. You can run nvim-dap with nothing but the REPL and never install a UI at all.

Installing nvim-dap and running a first debug session

The README treats nvim-dap as an ordinary Neovim plugin. One documented route is a plain git clone into a package directory on Neovim's start path:

git clone https://codeberg.org/mfussenegger/nvim-dap.git ~/.config/nvim/pack/plugins/start/nvim-dap

After that, generate the help tags so :help dap.txt resolves. The README gives two forms, :helptags ALL or :helptags <PATH-TO-PLUGIN/doc/>. Plugin managers are listed too: Plug 'mfussenegger/nvim-dap' with vim-plug, or use 'mfussenegger/nvim-dap' with packer.nvim. Supported Neovim versions are the latest nightly, 0.12.x (recommended) and 0.11.7.

The plugin alone will not debug anything yet. You need a debug adapter for your language, configured per language; the README points to :help dap-adapter, :help dap-configuration and the Debug-Adapter Installation wiki page for that. Once an adapter and a configuration exist, a typical flow starts with a breakpoint:

:DapToggleBreakpoint

The Lua equivalent is require'dap'.toggle_breakpoint(). Sessions are started and resumed with :DapNew and :DapContinue, or require'dap'.continue(). Stepping uses :DapStepOver and :DapStepInto, or require'dap'.step_over() and require'dap'.step_into(). To look at state, open the REPL:

require'dap'.repl.open()

Type an expression and press ENTER to evaluate it. The README also suggests a keymap convention for stepping, since arrow directions match the movement: down for step over, right for step into, left for step out, up for restart frame, and notes that keymaps can be set temporarily during a session with event listeners.

What nvim-dap does not do, and where that bites

The non-goals are the honest part of the README. Debug adapter installation is out of scope, full stop. That means the first hour with nvim-dap is usually spent on the adapter, not the plugin: finding the right adapter for your language, installing it through your system package manager, and writing a configuration that launches or attaches correctly. If that work is not something you want, nvim-dap is the wrong tool regardless of how well the client itself works.

The wiki is community maintained, and the README says so twice. It also warns that debug adapters may have changed since the instructions were written, and suggests reading the adapter's release notes or trying an older version if the wiki steps fail. That is a real failure mode: your debugging problem may be a stale wiki page, not a broken plugin. The README asks users to update the wiki when they find outdated examples, which is a reasonable ask but also an admission that the documentation trails the adapters.

Vim support is another hard boundary. The README states it is not going to happen and points Vim users to vimspector. And the feature list, while broad (conditional breakpoints, logpoints, exception breakpoints, step back and reverse continue, goto, restart, pause, evaluate), is a checklist of protocol operations, not a promise that every adapter implements all of them. Reverse debugging in particular depends entirely on what the adapter supports.

nvim-dap versus vimspector, and the extension ecosystem around it

The README lists exactly one alternative: vimspector. The difference in approach is where the debugger lives. vimspector is a Vim and Neovim plugin that carries its own adapter installation and UI story, which is why the README sends Vim users there. nvim-dap takes the opposite position: it is a DAP client library first, with a small command surface, and it pushes adapter management to your existing tooling and interface work to separate plugins. If you want one install that tries to cover adapters and panels for you, vimspector is the closer match. If you want a thin protocol layer that composes with the rest of your Neovim setup, nvim-dap is built for that.

Around the core, the README names three UI extensions with distinct scopes. nvim-dap-ui provides an IDE-like layout. nvim-dap-view sits between nvim-dap-ui and the built-in widgets. nvim-dap-virtual-text shows inline values. The README recommends language-specific extensions over manual configuration where they exist, on the grounds that they are usually better maintained. That recommendation is worth taking literally: a maintained extension for your language is likely to save you the adapter configuration work the core refuses to do.

Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-11, which is recent. Releases are infrequent and deliberate: 0.8.0 on 2024-05-30, 0.9.0 on 2024-12-20, and 0.10.0 on 2025-03-26. Between those tags the project moves on master, so if you track the default branch you are tracking unreleased code.

The licence is GPL-3.0. That is a copyleft licence, and it is worth checking how it interacts with your own distribution plans before you vendor or repackage the plugin; this article is not legal advice, and the LICENSE.txt in the repository is the authoritative text.

The upgrade cost is mostly not in the plugin. Because adapters are installed separately, a broken debug session after an upgrade can come from the adapter, from your configuration, or from nvim-dap itself, and the README's own advice for that situation is to check the adapter's release notes or try an older adapter version. Pinning your adapter version alongside your Neovim version is the practical way to keep the number of moving parts small.

Editorial conclusion

Adopt nvim-dap if you already live in Neovim and are willing to install a debug adapter per language yourself; the core plugin only speaks DAP and leaves adapter installation to your package manager, Nix or Ansible. Skip it if you want a debugger that arrives preconfigured, or if you are on Vim, where the README points to vimspector and states Vim support is not planned. Before committing, verify that a debug adapter exists for your language, that your Neovim version is 0.11.7 or newer, and that the adapter's own release notes still match the wiki instructions, since the wiki is community maintained and can lag behind adapter changes.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. mfussenegger/nvim-dap on GitHub
3. Project website
4. README
5. Releases