This page is about debugging your programs. To see info about debugging Emacs itself, see: DebugEmacs.

Debugging without a Debugger

If you like to debug your code by inserting output statements at critical/interesting points, have a look at ll-debug.el, available at

It has functions to insert output statements that display unique strings and skeletons to construct code to print out values of variables. There are some routines to comment lines or regions of code in an uniform way, too. Among the supported languages are Lisp, C, C++, Perl etc.

Elisp newbies needing to “just print stuff” (e.g., value of a variable) to *Messages* and the minibuffer? Use ‘message’:

    (message "logging %S" foo)

Debugging with GUD

Both Emacs and XEmacs ship with the GrandUnifiedDebugger (GUD) for interacting with a command-line debugger (such as gdb). GUD does useful things like displaying source code listings in an Emacs buffer (so that you can effectively step through code in your editor), providing consistent Emacs-like keybindings for various debugger commands (such as setting breakpoints and stepping through code), and a variety of other enhancements that make using a debugger with Emacs a more productive experience. For more information on GUD, see:

What about using it in emacs? For me, it seems no different than running gdb in a shell. Can someone do a step by step for a small simple program like the looping hello world with a breakpoint and source buffer? GUD seems not to do the useful thing of displaying the source code listing in an emacs buffer. Maybe I need a EmacsGUDTutorial.

It should display the source code listing. Did you compile with -g? The Emacs info manual (now included with Emacs 22) describes debugging with Emacs. See for a tutorial. – NickRoberts

 #include <stdio.h>
 int main(int argc, char* argv[]){
  int i;
  printf("hello world\n");
  for ( i=0;i<10;++i){
    printf("%d \n",i);
  return 0;

Not step by step, but:

The Perl debugger cannot (yet) be used via the GUD interface. It has its own interface. Start it via M-x perldb.

M-x perldb is part of the GUD interface. GUD stands for grand unified debugger. --NickRoberts

Completion can be used as a way of passing a list of potential executables with their complex paths destined for gdb. All one needs for completion is a list of files to be read into using something like SubprocessCompletion. One can generate a list of potential candidates using find:

 $ find . -xtype f -perm +111 -print0 | xargs -0 file | grep "ELF"
 ./src/gtk-gnutella:              ELF 64-bit LSB executable, AMD x86-64, version 1 (SYSV), for GNU/Linux 2.6.6, dynamically linked (uses shared libs), not stripped

A nice way of getting that into a list is to strip everything after the colon (assuming no executable exists with a colon in its name (a reasonable assumption)) with cut:

       cut -f1 -d:

NickRoberts is working on a version of GUD, GdbMode, specialised for GDB. It has been released as part of Emacs 22.

Does GUD work with valgrind in a way that valgrind offers to pass the session’s debugging to a gdb run from emacs? I.e., I’d like to have the full power of GUD instead of plain gdb from command line when using valgrind. – Dirk

See for one trick. I think you can do “set ann 1” (or even “set ann 3”) after attaching to GDB. I’m not sure how useful this is as memory violations are only a small part of Valgrind and I don’t think it attaches to GDB for memory leaks which is it’s main use. --NickRoberts

How do you start multiple gdb sessions from emacs? – TimotheeBesset

Though I haven’t tried it (I can’t get single debug to work) apparently with Emacs 22 there are is a package for multi debug sessions.


Multiple sessions are possible if you replace the GDB option “--annotate=3” with “--fullname”. This gives the the old basic behaviour as used in Emacs 21 and is called “text command mode” in the manual. It’s not perfect: there is only one overlay arrow and GUD commands can get confused if you use two different debuggers, e.g., gdb and perldb. --NickRoberts

Multiple debug sessions are supported in realgud. It supports about a dozen different debuggers, two for Perl include perl5db, along with debuggers for Ruby, Python, POSIX shell, and even support for my GNU make debugger, remake.

– rocky

I have a large emacs window and I can’t find the GDB marker, ⇒. How can I make it blink or appear in red?

I use a snippet from here to highlight the marker line. I’ve made a trivial modification to make it higlight the entire line, as opposed to the original which only highlights it up to the newline character of the current line. The original code is commented out below, and the entire thing is tested and working in GNU Emacs 23. – StefanKangas

  (defvar gud-overlay
    (let* ((ov (make-overlay (point-min) (point-min))))
      (overlay-put ov 'face 'secondary-selection)
    "Overlay variable for GUD highlighting.")
  (defadvice gud-display-line (after my-gud-highlight act)
    "Highlight current line."
    (let* ((ov gud-overlay)
           (bf (gud-find-file true-file)))
      (with-current-buffer bf
        (move-overlay ov (line-beginning-position) (line-beginning-position 2)
      ;;(move-overlay ov (line-beginning-position) (line-end-position)
  (defun gud-kill-buffer ()
    (if (derived-mode-p 'gud-mode)
        (delete-overlay gud-overlay)))
  (add-hook 'kill-buffer-hook 'gud-kill-buffer)

Realgud, a total rewrite of GUD

In short, see the realgud wiki or realgud github project. It is available from melpa as well.

GUD is one huge monolithic program written in a style that doesn’t make much use of Lisp data structures. Rocky Bernstein once extended that for his bash debugger and for a while it was in GNU Emacs. But since GUD is part of the emacs core and tied to that release cycle, bug fixes and changes were slow to happen.

The straw that broke Rocky’s back was the fact that you could debug only one thing at a time and fixing this was not a simple matter, due to the pervasive global variables.

So Rocky embarked on this journey to rewrite gud from the ground up using more current programming technology (more modularity, better use of Lisp, and more tests), and more current debuggers – well, okay, they were initially largely Rocky’s debuggers. See realgud debuggers available though for the current list.

CategoryDebug CategoryProgrammerUtils CategoryProgramming CategoryModes