Debugging in Vim

Vim 8.1 was released in May 2018. The “main new feature” was official support for running a terminal within vim. Along with this came a built-in debugger plugin, termdebug, which provides a visual interface for interacting with gdb. This post walks through an example session using termdebug.

Let’s use termdebug to step through and inspect the following C program that calculates the factorial of a number. I’ll be using Ubuntu 18.04, along with a version of vim installed from the Ubuntu repo—8.0.1453—that includes the relevant feature that was officially released as part of vim 8.1.

In addition to vim, a working version of gdb is required for debugging. For Ubuntu, this can be installed from the Ubuntu repo. For macOS, gdb will have to be code signed, and I’ve found that gdb versions earlier than 8.3 are problematic (tested on macOS Mojave). I haven’t tested debugging on Windows. Before trying to debug with vim, I suggest verifying that gdb works as expected on your system.

The path and/or name of gdb can be modified by setting the termdebugger variable before invoking the termdebug plugin.

Loading the termdebug Plugin

After loading the factorial.c source code, let’s load the plugin.

:packadd termdebug

The tab will split into three windows, which I’ve rearranged so that the editor window is on the right, as shown below.

The top-left window is for interacting with gdb. The bottom-left window is for interacting with the program loaded by gdb. The editor window on the right—with the corresponding source code—will show breakpoints and highlight lines when stepping through a program. This window also has clickable buttons at the top for interacting with gdb.

Loading a Program

We’ll have to compile the code using the -g flag, which will include debugger information in the compiled program.

:!gcc -g factorial.c -o factorial

We can use the gdb window to load the program. In addition to <c-w> commands and/or mouse clicks, we can use the :Gdb command to jump to the gdb window. The following gdb command will load the program (highlighted in the image that follows).

(gdb) file factorial

Alternatively, we could have passed factorial as an argument when calling :Termdebug earlier.

Setting Breakpoints

Breakpoints can be set in the gdb window using ordinary gdb commands.

(gdb) b factorial
(gdb) b 23

Alternatively, breakpoints can be set by navigating to a line of code in the editor window and entering :Break.

Lines with breakpoints are indicated by >> in the editor window.

Breakpoints can be removed with gdb commands or by navigating to the relevant lines and entering :Delete. Update 2019/05/12 6:45pm ET: On my version of vim, :Delete is used to remove breakpoints, but this was changed to :Clear in a commit on March 3, 2018.

Program Execution

The :Run command starts the program.

:Run [args]

Or alternatively, a program can be launched by entering the run command directly in the gdb window.

(gdb) run [args]

In either case, [args] should be replaced by the program’s arguments. Let’s use the value 6 to run the factorial program.

Both :Run and (gdb) run will pause execution at the first breakpoint. An alternative way to launch a program is to use gdb’s start command, which will pause execution at the beginning of the program.

I’ve launched the program using the vim command :Run 6. Execution is paused at the first breakpoint, with the corresponding line highlighted.

Stepping through Code

There are various ways to step through a program.

  1. Invoking gdb stepping commands directly in the gdb window
  2. Clicking Step, Next, Finish, Cont, Stop, Eval in the editor window
  3. Issuing vim commands :Step, :Over, :Finish, :Continue, :Stop

Program Inspection

The values of variables can be inspected in various ways.

  1. Invoking gdb inspection commands directly in the gdb window
  2. Hovering your mouse over variables in the editor window
    1. This requires the +balloon_eval compile-time feature
    2. This worked for me in gvim, but didn’t work reliably when running vim in a terminal
  3. Issuing vim command :Evaluate {expr}
    Omitting {expr} will evaluate the expression under the cursor, which can also be performed by pressing K


After passing all breakpoints and running the program until termination, we can see 720 in the program window, which is the expected output for the calculation of 6!.

The built-in help page includes thorough documentation.

:help terminal-debug

21 replies on “Debugging in Vim”

Hi Beamer, I’ve rearranged the windows so that the editor window is on the right. To do this, I moved the cursor to the editor window and entered ctrl-w L.

Documentation for moving windows is at :help window-moving.

Hi Daniel. Are you aware of any plugin/.vimrc which builds on `termdebug` **AND** Vim 8.1’s terminal windows to provide an easier workflow?

I’m referring to keys being mapped to :Step, :Next, and the likes, for instance, as 6 or more keystrokes everytime I simply want to move to the next line are a bit too much.

Furthermore, I see that commands like `:packadd termdebug` and `:Termdebug vim` have to be run everytime I start a new Vim session.

I wonder if such a thing exists. There are some results on GitHub, but having your thoughts on this topic would be useful!

Hi Enrico,

I’m not aware of any plugins that build upon termdebug.

:packadd termdebug can be added in your .vimrc so that you don’t have to enter that command for each Vim session.

" Source the termdebug plugin
packadd termdebug

With that added, termdebug can be launched with :Termdebug or with a custom mapping in your .vimrc, like the example below that loads termdebug with <leader>td (where <leader> would be a backslash, unless modified from its default).

" Add mapping to load termdebug
noremap <silent> <leader>td :Termdebug<cr>

There are various ways to speed up the entry of :Step, :Over, and the others. The following approaches are mentioned in the blog post:

  1. Invoke gdb stepping commands directly in the gdb window
  2. Click Step, Next, Finish, Cont, Stop, Eval in the editor window

In case you’re looking for an alternative approach, the following custom mappings—or some variation—for your .vimrc may be helpful. These map the stepping commands to <leader>s and <leader>o (where <leader> would be a backslash, unless modified from its default).

" Add mappings for :Step and :Over
noremap <silent> <leader>s :Step<cr>
noremap <silent> <leader>o :Over<cr>

The >> symbols doesn’t appear neither the top bar, even If I use :Winbar.
Anyone know what it could be? I have terminal activated

Hi GGCristo, does the breakpoint symbol appear after you enter CTRL-L or :redraw! to redraw the screen? If so, there is seemingly a problem preventing the screen from being updated when it should be.

Thanks for answer, I have never seen << neither lines highlight, neither the clickable bar.
At first I tought that that windows it was a regular code source, but I can press K above a variable and it tells me it value, so it doesn't seem to be the problem here.

Hi Daniel.
how to switch to the source code window from the gdb window after i enter some commonds in the gdb windows? I tried , but that didn’t work.

Hi wckang, there are various ways to switch to the source window.

  1. Use ctrl-w commands to navigate away from the gdb window.
    • ctrl-w h
    • ctrl-w j
    • ctrl-w k
    • ctrl-w l
  2. Navigate to the desired window with a mouse click.
  3. Within the gdb window, switch to Terminal-Normal mode with ctrl-w N or ctrl-\ ctrl-n, followed by :Source. Terminal-Job mode can be entered with i in the gdb window for entering additional gdb commands there.

Hi Daniel.
I have another question:how to remap the shortcuts in termdebug? In my neovim configure, the K has been mapped, so that will conflict the K in termdebug.

The K key in termdebug is equivalent to :Evaluate. The following example maps this to <leader>K (where <leader> would be a backslash, unless modified from its default).

noremap <silent> <leader>K :Evaluate<cr>

Leave a Reply

Your email address will not be published. Required fields are marked *