github github
stars 756
issues 9
subscribers 6
forks 22



last month


This plugin adds virtual text support to nvim-dap. nvim-treesitter is used to find variable definitions.

Plug 'mfussenegger/nvim-dap'
Plug 'nvim-treesitter/nvim-treesitter', {'do': ':TSUpdate'}
Plug 'theHamsta/nvim-dap-virtual-text'

The hlgroup for the virtual text is NvimDapVirtualText (linked to Comment). Exceptions that caused the debugger to stop are displayed as NvimDapVirtualTextError (linked to DiagnosticVirtualTextError). Changed and new variables will be highlighted with NvimDapVirtualTextChanged (default linked to DiagnosticVirtualTextWarn).

The behavior of this plugin can be activated and controlled via a setup call


Wrap this call with lua <<EOF when you are using viml for your config:

lua <<EOF

or with additional options:

require("nvim-dap-virtual-text").setup {
    enabled = true,                        -- enable this plugin (the default)
    enabled_commands = true,               -- create commands DapVirtualTextEnable, DapVirtualTextDisable, DapVirtualTextToggle, (DapVirtualTextForceRefresh for refreshing when debug adapter did not notify its termination)
    highlight_changed_variables = true,    -- highlight changed values with NvimDapVirtualTextChanged, else always NvimDapVirtualText
    highlight_new_as_changed = false,      -- highlight new variables in the same way as changed variables (if highlight_changed_variables)
    show_stop_reason = true,               -- show stop reason when stopped for exceptions
    commented = false,                     -- prefix virtual text with comment string
    only_first_definition = true,          -- only show virtual text at first definition (if there are multiple)
    all_references = false,                -- show virtual text on all all references of the variable (not only definitions)
    clear_on_continue = false,             -- clear virtual text on "continue" (might cause flickering when stepping)
    --- A callback that determines how a variable is displayed or whether it should be omitted
    --- @param variable Variable
    --- @param buf number
    --- @param stackframe dap.StackFrame
    --- @param node userdata tree-sitter node identified as variable definition of reference (see `:h tsnode`)
    --- @param options nvim_dap_virtual_text_options Current options for nvim-dap-virtual-text
    --- @return string|nil A text how the virtual text should be displayed or nil, if this variable shouldn't be displayed
    display_callback = function(variable, buf, stackframe, node, options)
      if options.virt_text_pos == 'inline' then
        return ' = ' .. variable.value
        return .. ' = ' .. variable.value
    -- position of virtual text, see `:h nvim_buf_set_extmark()`, default tries to inline the virtual text. Use 'eol' to set to end of line
    virt_text_pos = vim.fn.has 'nvim-0.10' == 1 and 'inline' or 'eol',

    -- experimental features:
    all_frames = false,                    -- show virtual text for all stack frames not only current. Only works for debugpy on my machine.
    virt_lines = false,                    -- show virtual lines instead of virtual text (will flicker!)
    virt_text_win_col = nil                -- position the virtual text at a fixed window column (starting from the first text column) ,
                                           -- e.g. 80 to position at column 80, see `:h nvim_buf_set_extmark()`

With support for inline virtual text (nvim 0.10), virt_text_pos = 'inline'


With highlight_changed_variables = false, all_frames = false


With highlight_changed_variables = false, all_frames = true


It works for all languages with locals.scm in nvim-treesitter (@definition.var is required for variable definitions). This should include C/C++, Python, Rust, Go, Java...



The virtual text can additionally use a comment-like syntax to further improve distinguishability between actual code and debugger info by setting the following option:

require("nvim-dap-virtual-text").setup {
  commented = true,

This will use the commentstring option to choose the appropriate comment-syntax for the current filetype


With virt_text_win_col = 80, highlight_changed_variables = true (x has just changed its value)


Show Stop Reason on Exception

image image

Exception virtual text can be deactivated via

require("nvim-dap-virtual-text").setup {
  show_stop_reason = false,