Skip to content
This repository

Multi-language DBGP debugger client for Vim (PHP, Python, Perl, Ruby, etc.)

Merge pull request #138 from henningda/patch-1

Point Debian/Ubuntu users to the vim-nox package
latest commit f9f165da6f
Jonathan Cairns authored
Octocat-spinner-32 doc doc fix: missing bar January 26, 2014
Octocat-spinner-32 features Add vim messages to cucumber test failure errors January 20, 2014
Octocat-spinner-32 plugin Merge pull request #133 from blueyed/inputstream-probe-sleep January 27, 2014
Octocat-spinner-32 rubylib Add more cucumber features, e.g for eval September 25, 2013
Octocat-spinner-32 spec Fix breaking Vdebug spec July 19, 2013
Octocat-spinner-32 syntax Remove trailing whitespace from watch window July 19, 2013
Octocat-spinner-32 tests Fix remote path mapping tests August 16, 2013
Octocat-spinner-32 .gitignore Removed help tags from repo and added to gitignore, fixes #10 September 13, 2012
Octocat-spinner-32 .travis.php.ini Use custom php ini for travis builds September 04, 2013
Octocat-spinner-32 .travis.yml Add php5-xdebug to travis install September 05, 2013
Octocat-spinner-32 Gemfile Add cucumber with the beginnings of a test July 08, 2013
Octocat-spinner-32 Gemfile.lock Add cucumber with the beginnings of a test July 08, 2013
Octocat-spinner-32 HISTORY Update HISTORY for version 1.4.1 June 09, 2013
Octocat-spinner-32 LICENCE Renamed project to Vdebug and added help file August 09, 2012
Octocat-spinner-32 Merge pull request #138 from henningda/patch-1 March 03, 2014
Octocat-spinner-32 Rakefile Attempt to fix breaking cucumber tests on travis August 16, 2013
Octocat-spinner-32 VERSION Update version to 1.4.1 June 09, 2013
Octocat-spinner-32 Add build bash script for easier tarring March 06, 2013
Octocat-spinner-32 requirements.txt Backport unittests2 for python 2.6 compatibility December 21, 2012
Octocat-spinner-32 Backport unittests2 for python 2.6 compatibility December 21, 2012


Build Status

Vdebug is a new, fast, powerful debugger client for Vim. It's multi-language, and has been tested with PHP, Python, Ruby, Perl, Tcl and NodeJS. It interfaces with any debugger that faithfully uses the DBGP protocol, such as Xdebug for PHP.
There are step-by-step instructions for setting up debugging with all of the aforementioned languages in the Vim help file that comes with Vdebug.

It builds on the experience gained through the legacy of the Xdebug Vim script originally created by Seung Woo Shin and extended by so many others, but it's a total rebuild to allow for a nicer interface and support of new features.

It's written in Python, and has an object-oriented interface that is easy to extend and can even be used from the command-line. It even has unit tests covering some of the more critical parts of the code.

Getting help

If you're having trouble with Vdebug in any way, here are the steps you can take to get help (in the right order):

  1. Check the issues to see whether it's already come up.
  2. Visit the #vdebug irc channel on freenode, someone is normally there.
  3. Open a new issue.


Follow me on Twitter, @joonty, for Vdebug updates and release news.

19/07/2013: there's a known issue with Vdebug and Vim 7.4. Take a look at issue #98 to follow updates and fixes.

11/06/2013: Vdebug now has an irc channel on freenode! If you're running into problems installing, configuring or running vdebug, or you just want to ask a general question, join us on #vdebug.

Recent version (version 1.4.1)

  • Fix folds being forgotten after debugging (issue #56)
  • Don't overwrite features array if it exists (issue #59)
  • Mapping of single modes (thanks @xbot, #66)
  • Stop empty buffers from being created (issue #70)
  • Fix ElementTree deprecation warning (thanks @InFog, #89)
  • And more... check out the HISTORY file

How to use

First of all, scoot down to the quick guide below.

There is extensive help provided in the form of a Vim help file. This goes through absolutely everything, from installation to configuration, setting up debuggers for various languages, explanation of the interface, options, remote server debugging and more.

To get this help, type:

:help Vdebug

after installing the plugin. If this doesn't work, you will need to generate the help tags.

Generating help tags

Some package managers, such as Vundle, will automatically generate help tags. Others, such as Pathogen, won't by default, so you have to do it yourself. Also, if you have installed Vdebug manually then you will also have to do this step.

For pathogen users, you can add this to your vimrc file to automatically generate helptags for your plugins:

call pathogen#helptags()

To manually generate the tags, run this in vim:

:helptags /path/to/vdebug/doc

where the path supplied is vdebug's doc directory. This should enable vdebug's help to be accessed.



  • Vim compiled with Python 2.6+ support, tabs and signs (for Debian/Ubuntu this is provided in the vim-nox package)
  • A programming language that has a DBGP debugger, e.g. PHP, Python, Ruby, Perl, NodeJS, Tcl...


Clone or download a tarball of the plugin and move its content in your ~/.vim/ directory.

Your ~/.vim/plugins/ directory should now contain vdebug.vim and a directory called "python".

Using git and Pathogen

Clone this repository in your ~/.vim/bundle directory

Using vundle

Add this to your ~/.vimrc file:

Bundle 'joonty/vdebug.git'

Then, from the command line, run:

vim +BundleInstall +qall

Quick guide

Set up any DBGP protocol debugger, e.g. Xdebug. (See :help VdebugSetUp). Start Vdebug with <F5>, which will make it wait for an incoming connection. Run the script you want to debug, with the debugging engine enabled. A new tab will open with the debugging interface.

Once in debugging mode, the following default mappings are available:

  • <F5>: start/run (to next breakpoint/end of script)
  • <F2>: step over
  • <F3>: step into
  • <F4>: step out
  • <F6>: stop debugging
  • <F7>: detach script from debugger
  • <F9>: run to cursor
  • <F10>: set line breakpoint
  • <F11>: show context variables (e.g. after "eval")
  • <F12>: evaluate variable under cursor
  • :Breakpoint <type> <args>: set a breakpoint of any type (see :help VdebugBreakpoints)
  • :VdebugEval <code>: evaluate some code and display the result
  • <Leader>e: evaluate the expression under visual highlight and display the result

To stop debugging, press <F6>. Press it again to close the debugger interface.

If you can't get a connection, then chances are you need to spend a bit of time setting up your environment. Type :help Vdebug for more information.


If you have a problem, and would like to see what's going on under the hood or raise an issue, it's best to create a log file. You can do this by setting these options before you start debugging:

:VdebugOpt debug_file ~/vdebug.log
:VdebugOpt debug_file_level 2

Then start debugging, and you can follow what's added to the log file as you go. It shows the communication between the debugging engine and Vdebug.

If you're creating an issue then it's probably best to upload a log as a Gist, as it can be pretty large.


I gladly accept contributions to the code. Just fork the repository, make your changes and open a pull request with detail about your changes. There are a couple of conditions:


  • The tests use unittest2 and mock, so make sure they're installed
pip install unittest2
pip install mock
  • To run the tests, run python in the top directory of the plugin


This plugin is released under the MIT License.

Something went wrong with that request. Please try again.