RealGUD: driving PDB and GDB from an Emacs source window

A debugger REPL and a source buffer, side by side

RealGUD is described as an extensible, modular GNU Emacs front-end for interacting with external debuggers, and the repository calls itself the Grand Cathedral Debugger rewrite. The model is simple once you see it. You open a source file and start a debugger with an interactive command, and RealGUD opens two windows. The command window shows the debugger's REPL, so everything the debugger itself supports still works, including the commands you already know. The source window shows your code. In it, most single keys correspond to a debugger action, so you can step through your program without moving your attention to the REPL and without leaving the buffer you are reading. The current line is marked with a solid arrow, and gray arrows mark the previous positions, which gives you a visual history of where execution has been.

Single keys do the stepping in the source window

The keybinding table is the heart of the package, and it is dense enough to be worth reading in full before you start. Motion commands cover the usual actions: n or F10 for next, which is step over or step through, s or SPC or F11 to step into, f or S-F11 to finish, that is step out or return, and c or F5 to continue to the next break point. Breakpoints are set with b or F9 and cleared by number with D. Variables are inspected with the middle mouse button, which shows the value under the cursor in a tooltip, and e evaluates an expression. Control commands are q or S-F5 to quit, R or r to run, which is a restart, and S to move to the command window. Commands marked as mouse commands can also be run from the tool bar under tool-bar-mode or from the menu under menu-bar-mode.

Stack frames, until and breakpoint toggling

Beyond the everyday keys there is a second group of extra commands, and the documentation marks the unfinished ones as work in progress with contributions welcome. U runs until a greater source line is reached. u and > move up the stack to an older stack frame, and d and < move down to a younger one, which is how you inspect a caller without leaving the source window. X clears a breakpoint by line rather than by number, which is what you want once the numbering is confusing. j jumps to the current line, - disables a breakpoint and + enables it again, both marked as in progress. The distinction between step, next and finish is the one most newcomers fight with, and having them bound to single keys in the buffer, with F10, F11 and S-F11 as function key equivalents, is what makes the flow of a debugging session feel continuous.

Installing through MELPA takes two commands

RealGUD is distributed as an Emacs package on MELPA, and if you do not have MELPA configured you add it to your .emacs and restart Emacs:

(require 'package)
(add-to-list 'package-archives '("melpa" . "http://melpa.org/packages/") t)
(package-initialize)

After that the package can be installed from inside Emacs, first refreshing the package database and then installing the package and its dependencies:

M-x package-refresh-contents RET      (to refresh your package database)
M-x package-install RET realgud RET   (to install and compile `realgud` and its dependencies)

There are other routes if you prefer them: el-get, or installation from source, with the project wiki holding an article on how to install. The source tree supports that path too, with autogen.sh, configure.ac, Makefile.am, a Cask file for development dependencies and install-from-git.sh. For a quick trial without installing anything, the quick start is a single interactive command, M-x load-library RET realgud RET, which loads the package into the current session.

Launching a debugger or attaching to one already running

Starting a session uses a namespaced interactive command, M-x realgud:<debugger-name>. The README gives two examples: realgud:pdb launches PDB, the Python debugger, and realgud:gdb is the GDB front-end. The behaviour is not identical across backends, and the documentation is candid about it. With some debuggers, such as the GDB one, the source window does not appear until you type start in the command window, because the debugger has to be told to run before it has a location to point at. The second mode is for the case where the debugger is already running. Inside an existing shell or eshell buffer, M-x realgud-track-mode tracks an already-running debugger process, which is the arrangement for a long lived session or for a debugger started by hand inside Emacs.

One front-end per debugger, and the wiki as the map

The architecture is modular in the sense that each debugger gets its own front-end module, and the project supports many external debuggers through a list kept in the wiki, with a separate wiki page explaining how to add a new debugger. That is where the honest limit of this README sits: the supported debugger list is not enumerated here, so the answer to can RealGUD drive my debugger lives in the wiki rather than in the documentation you are reading. The wiki also carries pages for setting up, using realgud and exploring features. The repository layout supports that modularity, with the entry point realgud.el at the top level, a realgud/ directory holding the per-debugger code, an etc/ directory for assets such as the logo and screenshots, and a test/ directory for the test suite.

Seven years between the last release and the last push

The maintenance picture needs two dates. The last push to the master branch was on 2026-08-21, so the repository is receiving changes within the last couple of months. The releases are much older: 1.5.1 from 2019-07-15, 1.5.0 from 2019-05-28, and 1.4.8, tagged Memorial Day, from 2019-05-26. So the package you install from MELPA and the code in the repository are not obviously the same thing, and the project wiki, not the release notes, is the practical guide to current behaviour. The licence field on the repository says GPL-3.0, and the COPYING file sits at the top level next to AUTHORS, THANKS, ChangeLog and NEWS, which is the classic GNU project layout, so redistribution of a modified copy carries the usual copyleft obligations. The build system is the autotools one, with configure.ac and common.mk.in, and CI ran on Travis with run-travis-ci.sh and travis.sh present in the tree.

Editorial conclusion

Adopt RealGUD if you already live in Emacs and want your Python, C or other external debugger to share the editor's buffers and key bindings instead of living in a separate terminal, and start with the source window commands, since that is where the difference from a plain REPL shows. Do not adopt it if your debugging happens in an IDE with its own visual debugger, or if you need a debugger backend that the project does not cover, since the supported list lives in the wiki and is not enumerated in the README. Verify first that your debugger has a RealGUD front-end for the version you use, that the MELPA package you install matches the code in the repository, given that the newest release tag is 1.5.1 from 2019-07-15, and that the Emacs version you run is one the package still installs on.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. realgud/realgud on GitHub
5. Releases