How do I step through a Vimscript command or function to debug it interactively?
Answer
:debug
Explanation
The :debug command prefix puts Vim into its built-in interactive debugger before executing the given command. You can step through execution line-by-line, inspect variables, and trace calls into functions — all without leaving the editor. This is invaluable for diagnosing unexpected behavior in vimrc files, plugins, or complex mappings.
How it works
Prefix any Ex command with :debug to enter debug mode:
:debug source ~/.vimrc
:debug call MyFunction()
:debug normal @q
At each step, Vim shows the line about to execute and pauses for a debugger command. The available debugger commands are:
| Command | Action |
|---|---|
cont |
Continue to next breakpoint |
next |
Execute current line, stop on next |
step |
Step into function calls |
finish |
Run to end of current function |
quit |
Abort execution |
bt |
Show call stack backtrace |
echo {expr} |
Evaluate and print an expression |
Example
Debugging a sourced file:
:debug source $MYVIMRC
> /home/user/.vimrc
line 1: " Personal vimrc
Enter debug command: next
line 2: set nocompatible
Enter debug command: echo &expandtab
1
Enter debug command: cont
Tips
- Combine with
:breakadd func {funcname}to set a breakpoint inside a specific function — then use:debug call OtherFunc()to run until that breakpoint fires - Clear all breakpoints with
:breakdel * - Use
:echo v:errmsgto inspect the last error message without entering debug mode