Voltron is an extensible debugger UI toolkit written in Python.




Voltron is an extensible debugger UI toolkit written in Python. It aims to improve the user experience of various debuggers (LLDB, GDB, VDB and WinDbg) by enabling the attachment of utility views that can retrieve and display data from the debugger host. By running these views in other TTYs, you can build a customised debugger user interface to suit your needs.

Voltron does not aim to be everything to everyone. It's not a wholesale replacement for your debugger's CLI. Rather, it aims to complement your existing setup and allow you to extend your CLI debugger as much or as little as you like. If you just want a view of the register contents in a window alongside your debugger, you can do that. If you want to go all out and have something that looks more like OllyDbg, you can do that too.

Built-in views are provided for:

  • Registers
  • Disassembly
  • Stack
  • Memory
  • Breakpoints
  • Backtrace

The author's setup looks something like this:

voltron example LLDB

Any debugger command can be split off into a view and highlighted with a specified Pygments lexer:

command views

More screenshots are here.


Voltron supports LLDB, GDB, VDB and WinDbg/CDB (via PyKD) and runs on macOS, Linux and Windows.

WinDbg support is still fairly new, please open an issue if you have problems.

The following architectures are supported:

lldb gdb vdb windbg


Note: Only macOS and Debian derivatives are fully supported by the install script. It should hopefully not fail on other Linux distros, but it won't try to install package dependencies. If you're using another distro, have a look at install.sh to work out what dependencies you might need to install before running it.

Download the source and run the install script:

$ git clone https://github.com/snare/voltron
$ cd voltron
$ ./install.sh

By default, the install script will install into the user's site-packages directory. If you want to install into the system site-packages, use the -s flag:

$ ./install.sh -s

You can also install into a virtual environment (for LLDB only) like this:

$ ./install.sh -v /path/to/venv -b lldb

If you are on Windows without a shell, have problems installing, or would prefer to install manually, please see the manual installation documentation.

Quick Start

  1. If your debugger has an init script (.lldbinit for LLDB or .gdbinit for GDB) configure it to load Voltron when it starts by sourcing the entry.py entry point script. The full path will be inside the voltron package. For example, on macOS it might be /Library/Python/2.7/site-packages/voltron/entry.py. The install.sh script will add this to your .gdbinit or .lldbinit file automatically if it detects GDB or LLDB in your path.


     command script import /path/to/voltron/entry.py


     source /path/to/voltron/entry.py
  2. Start your debugger and initialise Voltron manually if necessary.

    On recent versions of LLDB you do not need to initialise Voltron manually:

     $ lldb target_binary

    On older versions of LLDB you need to call voltron init after you load the inferior:

     $ lldb target_binary
     (lldb) voltron init


     $ gdb target_binary


     $ ./vdbbin target_binary
     > script /path/to/voltron/entry.py

    WinDbg/CDB is only supported run via Bash with a Linux userland. The author tests with Git Bash and ConEmu. PyKD and Voltron can be loaded in one command when launching the debugger:

     $ cdb -c '.load C:\path\to\pykd.pyd ; !py --global C:\path\to\voltron\entry.py' target_binary
  3. In another terminal (I use iTerm panes) start one of the UI views. On LLDB, WinDbg and GDB the views will update immediately. On VDB they will not update until the inferior stops (at a breakpoint, after a step, etc):

     $ voltron view register
     $ voltron view stack
     $ voltron view disasm
     $ voltron view backtrace
  4. Set a breakpoint and run your inferior.

     (*db) b main
     (*db) run
  5. When the debugger hits the breakpoint, the views will be updated to reflect the current state of registers, stack, memory, etc. Views are updated after each command is executed in the debugger CLI, using the debugger's "stop hook" mechanism. So each time you step, or continue and hit a breakpoint, the views will update.


See the wiki on github.


Q. Why am I getting an ImportError loading Voltron?

A. You might have multiple versions of Python installed and have installed Voltron using the wrong one. See the more detailed installation instructions.

Q. GEF? PEDA? PwnDbg? fG's gdbinit?

A. All super great extensions for GDB. These tools primarily provide sets of additional commands for exploitation tasks, but each also provides a "context" display with a view of registers, stack, code, etc, like Voltron. These tools print their context display in the debugger console each time the debugger stops. Voltron takes a different approach by embedding an RPC server implant in the debugger and enabling the attachment of views from other terminals (or even web browsers, or now synchronising with Binary Ninja), which allows the user to build a cleaner multi-window interface to their debugger. Voltron works great alongside all of these tools. You can just disable the context display in your GDB extension of choice and hook up some Voltron views, while still getting all the benefits of the useful commands added by these tools.

Bugs and Errata

See the issue tracker on github for more information or to submit issues.

If you're experiencing an ImportError loading Voltron, please ensure you've followed the installation instructions for your platform.


On older versions of LLDB, the voltron init command must be run manually after loading the debug target, as a target must be loaded before Voltron's hooks can be installed. Voltron will attempt to automatically register its event handler, and it will inform the user if voltron init is required.


More information about WinDbg/CDB support here.


The authors primarily use Voltron with the most recent version of LLDB on macOS. We will try to test everything on as many platforms and architectures as possible before releases, but LLDB/macOS/x64 is going to be by far the most frequently-used combination. Hopefully Voltron doesn't set your pets on fire, but YMMV.


See the LICENSE file.

If you use this and don't hate it, buy me a beer at a conference some time. This license also extends to other contributors - richo definitely deserves a few beers for his contributions.


Thanks to my former employers Assurance and Azimuth Security for giving me time to spend working on this.

Props to richo for all his contributions to Voltron.

fG!'s gdbinit was the original inspiration for this project.

Thanks to Willi for implementing the VDB support.

Voltron now uses Capstone for disassembly as well as the debugger hosts' internal disassembly mechanism. Capstone is a powerful, open source, multi-architecture disassembler upon which the next generation of reverse engineering and debugging tools are being built. Check it out.

Thanks to grazfather for ongoing contributions.

  • Exception <class 'ImportError'> raised while loading Voltron: No module named 'plugin'

    Exception raised while loading Voltron: No module named 'plugin'


    just spent last 2-3 days in implementing a python server inside gdb, with some external views that can be started in different terminals (register, stack etc.). And accidentally bumped into this project! Briliant!!!!

    just that... did not manage to make it working... got the error above.

    default python is the same version for gdb and the one found in path (both are 3.4)

    thanks in advance for your help

    opened by mobiphil 53
  • AttributeError: 'NoneType' object has no attribute 'adaptor_class'

    AttributeError: 'NoneType' object has no attribute 'adaptor_class'

    I build the latest Voltron from GitHub and install in Windows following the instructions at https://github.com/snare/voltron/wiki/Installation#windbg and receive the following error in my WinDbg Command log:

    0:000> .load pykd 0:000> !py --global C:\Python27\Lib\site-packages\voltron-0.1.5-py2.7.egg\voltron\entry.py C:\Python27\lib\site-packages\blessed\terminal.py:32: UserWarning: One or more of the modules: 'termios', 'fcntl', and 'tty' are not found on your platform 'win32'. The following methods of Terminal are dummy/no-op unless a deriving class overrides them: setraw, cbreak, kbhit, height, width warnings.warn(_MSG_NOSUPPORT) An error occurred while loading Voltron:

    Traceback (most recent call last): File "C:\Python27\Lib\site-packages\voltron-0.1.5-py2.7.egg\voltron\entry.py", line 98, in voltron.debugger = plugin.adaptor_class(*args) AttributeError: 'NoneType' object has no attribute 'adaptor_class'

    opened by trietptm 29
  • Implicitly Setting an Architecture

    Implicitly Setting an Architecture

    I have issues (Ubu 14.04, lldb 3.7) with voltron views recognizing architecture types. I tried compiling from both clang and gcc.

    file reports: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked (uses shared libs), for GNU/Linux 2.6.24, BuildID[sha1]=, not stripped

    I am thinking about just modifying register.py to implicitly set an architecture - I could submit a pull request if there's no resources to support this. I realize this is more a feature request than a bug. It looks like we could possibly just add an argument to configure_subparser and then I would have to spend a few minutes digging into where targets sets it to propagate properly. Shouldn't be too difficult. Let me know if you think i should just do it and submit a pull request.


    -- q

    opened by theqlabs 24
  • No voltron views work.

    No voltron views work.

    arm-none-eabi-gdb v 7.4.50. Inferior started by running source /..../voltron.py as the very first thing I do::

    source /usr/local/lib/python2.7/dist-packages/voltron/entry.py set pagination off layout src fs cmd target remote localhost:2331 monitor flash device = LPC1763 monitor speed adaptive monitor reset

    Installed the latest version of Voltron through pip. (you probably want to rename voltron to voltron-X.Y)

    This from "voltron view break"

    Traceback (most recent call last): File "/usr/local/lib/python2.7/dist-packages/voltron/view.py", line 252, in run msg = e.message.args[1].strerror IndexError: tuple index out of range

    Error: HTTPConnectionPool(host='localhost', port=5555): Max retries exceeded with url: /api/request (Caused by NewConnectionError('<requests.packages.urllib3.connection.HTTPConnection object at 0x7ffff1fca390>: Failed to establish a new connection: [Errno 111] Connection >

    opened by mikaelj 19
  • Interrupted System Call

    Interrupted System Call

    Really trying to get this to work on a 32-bit Ubuntu 12.04 LTS VM. I can get everything installed/compiled/etc. "Voltron loaded" appears in a glowing red when I fire up GDB, my .gdbinit has the source and init lines but I have two issues:

     Starting program: myFile 9999
     Exception in thread Thread-1:
     Traceback (most recent call last):
     File "/usr/lib/python2.7/threading.py", line 551, in __bootstrap_inner
     File "/usr/local/lib/python2.7/dist-packages/voltron-0.1-py2.7.egg/voltron/core.py", line 193, in run
     rfds, _, _ = select.select([serv, self.exit_pipe] + self.clients, [], [])
     error: (4, 'Interrupted system call')'

    and then in my second terminal, when trying to start a view, I get:

     Error connecting to server: Connection refused

    Thanks for any guidance you can provide.

    opened by theqlabs 17
  • [Feature Request] cdb support

    [Feature Request] cdb support

    An idea I was playing with was cdb support for Voltron.

    cdb is the console based windbg, and as windbg can load python addons I thought Voltron might be a great addition.

    I have been thinking for over a month to implement this myself, although it seems I don't have enough spare time to get started with it. Decided to dump the idea here so everybody can comment on the idea and or implement it.

    opened by Stolas 16
  • error: Could not find suitable distribution for Requirement.parse('yaml')

    error: Could not find suitable distribution for Requirement.parse('yaml')

    Hello! I've been trying to get this set up for a while, maybe you can tell me what I am doing wrong. I get this error when using setup.py install....

    error: Could not find suitable distribution for Requirement.parse('yaml')

    Any Ideas?

    opened by ghost 16
  • Problem with gdbinit

    Problem with gdbinit

    Hey, me again. gdb 7.4.1-debian is giving me this error:

    Exception <type 'exceptions.ImportError'> raised while loading Voltron: No module named blessed
    /home/admin/.gdbinit:2: Error in sourced command file:
    Undefined command: "voltron".  Try "help".

    I'm assuming this is from the 'import blessed' line in dbgentry.py. Any ideas?

    Sorry I'm treating this as a forum since there's no official forum for voltron. Cheers

    opened by defau1t 15
  • It's not working on Ubuntu 14.04

    It's not working on Ubuntu 14.04

    [email protected]:~$ gdb -q
    Traceback (most recent call last):
      File "/usr/local/lib/python2.7/dist-packages/voltron-0.1-py2.7.egg/dbgentry.py", line 1, in <module>
        import voltron
    ImportError: No module named 'voltron'
    /home/user/.gdbinit:2: Error in sourced command file:
    Undefined command: "voltron".  Try "help".
    [email protected]:~$ cat .gdbinit 
    source /usr/local/lib/python2.7/dist-packages/voltron-0.1-py2.7.egg/dbgentry.py
    voltron start
    [email protected]:~$ which voltron 
    [email protected]:~$ python
    Python 2.7.6 (default, Mar 22 2014, 22:59:56) 
    [GCC 4.8.2] on linux2
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import voltron
    >>> voltron.__file__
    opened by blacktop 15
  • segfault on gdb 7.9

    segfault on gdb 7.9

    os: Ubuntu 15.04 gdb: GNU gdb (Ubuntu 7.9-1ubuntu1) 7.9 elf file is https://github.com/ctfs/write-ups-2015/tree/master/defcon-qualifier-ctf-2015/reverse/pr0dk3y

    i do load the file with gdb: gdb ./pr0dk3y_40687b492c80205cccb34db1eabf6456 bp *0 to break as soon as it executes then info file, bpd 1 and bp *entry_point (this is to break on entry point since the elf has PIE)

    it will break and seems to work but as soon as i single step one or at most two instructions (either si/ni) gdb will segfault:

    0x0000555555554a65 in ?? ()
    /build/buildd/gdb-7.9/gdb/common/cleanups.c:265: internal-warning: restore_my_cleanups has found a stale cleanup
    A problem internal to GDB has been detected,
    further debugging may prove unreliable.
    This is a bug, please report it.  For instructions, see:
    [1]    5903 abort (core dumped)  gdb pr0dk3y_40687b492c80205cccb34db1eabf6456


    Traceback (most recent call last):
      File "/usr/local/lib/python3.4/dist-packages/voltron-0.1-py3.4.egg/voltron/core.py", line 215, in run
        rfds, _, _ = select.select([serv, self.exit_pipe] + self.clients, [], [])
    InterruptedError: [Errno 4] Chiamata di sistema interrotta
    During handling of the above exception, another exception occurred:
    Traceback (most recent call last):
      File "/usr/lib/python3.4/threading.py", line 920, in _bootstrap_inner
      File "/usr/local/lib/python3.4/dist-packages/voltron-0.1-py3.4.egg/voltron/core.py", line 218, in run
        if ex[0] == errno.EINTR: # interrupted system call
    TypeError: 'InterruptedError' object is not subscriptable
    0x0000555555554a84 in ?? ()

    here is my gdb-init:

    source ~/coding_home/reversing/voltron/dbgentry.py                                                                                                                                                                                         
    voltron init                                                                                                                                                                                                                               
    #source ~/.fg_gdbinit

    i did both import and remove https://github.com/gdbinit/Gdbinit but still keeps on crashing.

    opened by ocean1 14
  • lldb (macos) views don't update

    lldb (macos) views don't update

    Thanks for this really cool toolkit.

    I'm just experimenting with lldb+macos and I can't seem to get the views to update automatically. I start my executable, voltron indicates it loaded fine. I start a view in another window and it shows me expected output for the the given debugee. However, as I step through the code, the views do not update until I send a to the window with the view (press the return key). Is this some sort of configuration that I can change or possibly something odd about my environment?

    I typically use tmux+iTerm for my shells and I've tried both with and without tmux just to eliminate that as a possible cause. I've also using the standard Terminal app in macos. All exhibit the same behavior.

    lldb version is:

    lldb-1000.11.37.1 Swift-4.2

    and system python is 2.7.10.

    I DO have homebrew installed (including its python versions), but I've tried to be careful not to load homebrew stuff from lldb/voltron.

    any advice appreciated.

    opened by mellery451 12
  • Issue with fresh installation

    Issue with fresh installation

    An error occurred while loading Voltron:

    Traceback (most recent call last): File "/users/anksingh/.local/lib/python2.7/site-packages/voltron/entry.py", line 57, in import voltron File "/users/anksingh/.local/lib/python2.7/site-packages/voltron/init.py", line 95, in setup_env() File "/users/anksingh/.local/lib/python2.7/site-packages/voltron/init.py", line 31, in setup_env pkg_plugins=PluginDirectory('plugins', parent=PackageDirectory()) File "/users/anksingh/.local/lib/python2.7/site-packages/scruffy/env.py", line 49, in init self.add(**kwargs) File "/users/anksingh/.local/lib/python2.7/site-packages/scruffy/env.py", line 114, in add self._children[key].prepare() File "/users/anksingh/.local/lib/python2.7/site-packages/scruffy/file.py", line 439, in prepare self.load() File "/users/anksingh/.local/lib/python2.7/site-packages/scruffy/file.py", line 445, in load self._pm.load_plugins(self.path) File "/users/anksingh/.local/lib/python2.7/site-packages/scruffy/plugin.py", line 65, in load_plugins self.load_plugins(filepath) File "/users/anksingh/.local/lib/python2.7/site-packages/scruffy/plugin.py", line 61, in load_plugins mod = imp.load_module(modname, file, path, descr) File "/users/anksingh/.local/lib/python2.7/site-packages/voltron/plugins/debugger/dbg_lldb.py", line 579 log.warning(f"Exception when saving hook index for unregistering. {e}") ^ ---Type to continue, or q to quit--- SyntaxError: invalid syntax

    opened by ankitsing 0
  • Added support for arm64e (Mac M1 and new iPhones) architecture on LLDB

    Added support for arm64e (Mac M1 and new iPhones) architecture on LLDB

    M1 Macs, newer iPhones and any device running on A12 Apple chipset run on a specific arm64e architecture that introduces some new features like PAC or nested virtualizations.

    Registers, instructions and basic core ARM components are mostly the same as for arm64, but Voltron does not support arm64e architecture as shown in my issue : https://github.com/snare/voltron/issues/297.

    Support for this arm64e architecture is not hard to implement thanks to the similarity of these two architecture versions, so here is my pull request to add this support on LLDB.

    It may work with other debuggers but I have only tested it with LLDB.

    opened by AdamTaguirov 0
  • Architecture 'arm64e' not supported

    Architecture 'arm64e' not supported


    Do you plan to support arm64e (Tested for Mac OS 12.3.1 Kernel) architecture in near future? Or is it already supported someway and the tool needs only a tweak to handle it? Capture d’écran 2022-05-17 à 19 23 25

    Thank you.

    opened by AdamTaguirov 0
  • ImportError – name clash when debugging MacOS Kernel with LLDB

    ImportError – name clash when debugging MacOS Kernel with LLDB

    I'm trying to remote debug MacOS kernel with LLDB. I have Voltron and Apple's Kernel Debug Kit installed.

    In LLDB, first I create the target:

    target create /Library/Developer/KDKs/KDK_11.6.5_20G527.kdk/System/Library/Kernels/kernel

    After that, once I set it to load scripts:

    settings set target.load-script-from-symbol-file true

    Then, it crashes with

    error: module importing failed: Traceback (most recent call last):
      File "<string>", line 1, in <module>
      File "/Library/Developer/KDKs/KDK_11.6.5_20G527.kdk/System/Library/Kernels/kernel.dSYM/Contents/Resources/Python/lldbmacros/xnu.py", line 1286, in <module>
        from misc import *
      File "/Library/Developer/KDKs/KDK_11.6.5_20G527.kdk/System/Library/Kernels/kernel.dSYM/Contents/Resources/Python/lldbmacros/misc.py", line 8, in <module>
        from scheduler import *
      File "/Library/Developer/KDKs/KDK_11.6.5_20G527.kdk/System/Library/Kernels/kernel.dSYM/Contents/Resources/Python/lldbmacros/scheduler.py", line 1035, in <module>
        from kevent import GetKnoteKqueue
      File "/Library/Developer/KDKs/KDK_11.6.5_20G527.kdk/System/Library/Kernels/kernel.dSYM/Contents/Resources/Python/lldbmacros/kevent.py", line 3, in <module>
        from memory import vm_unpack_pointer
    ImportError: cannot import name 'vm_unpack_pointer' from 'memory' (/Users/kon/Library/Python/3.8/lib/python/site-packages/voltron/plugins/api/memory.py)

    The problem seems to be that a file /Library/Developer/KDKs/KDK_11.6.5_20G527.kdk/System/Library/Kernels/kernel.dSYM/Contents/Resources/Python/lldbmacros/kevent.py tries to import stuff from memory, where the intended file for that is /Library/Developer/KDKs/KDK_11.6.5_20G527.kdk/System/Library/Kernels/kernel.dSYM/Contents/Resources/Python/lldbmacros/memory.py

    However, for some reason, it actually accesses Voltron's memory.py: /Users/me/Library/Python/3.8/lib/python/site-packages/voltron/plugins/api/memory.py

    I am not very well-versed in Pythons modules and import rules, and especially I don't know how LLDB loads scripts, but to me, this seems like something that is not normally supposed to happen. Is this just unfortunate name clash, or is something broken in my system?

    opened by golddranks 11
  • Theming for Voltron

    Theming for Voltron

    Is there any current way to change color scheme or theme of voltron?

    Are there any community themes as of yet?

    Are there any docs I can look at for the configuration of Voltron colors? Thanks!

    opened by caprinux 0
Full-screen console debugger for Python

PuDB: a console-based visual debugger for Python Its goal is to provide all the niceties of modern GUI-based debuggers in a more lightweight and keybo

Andreas Klöckner 2.5k Sep 26, 2022
Debugger capable of attaching to and injecting code into python processes.

DISCLAIMER: This is not an official google project, this is just something I wrote while at Google. Pyringe What this is Pyringe is a python debugger

Google 1.6k Sep 23, 2022
pdb++, a drop-in replacement for pdb (the Python debugger)

pdb++, a drop-in replacement for pdb What is it? This module is an extension of the pdb module of the standard library. It is meant to be fully compat

null 987 Sep 23, 2022
Graphical Python debugger which lets you easily view the values of all evaluated expressions

birdseye birdseye is a Python debugger which records the values of expressions in a function call and lets you easily view them after the function exi

Alex Hall 1.5k Sep 19, 2022
NoPdb: Non-interactive Python Debugger

NoPdb: Non-interactive Python Debugger Installation: pip install nopdb Docs: https://nopdb.readthedocs.io/ NoPdb is a programmatic (non-interactive) d

Ondřej Cífka 66 Sep 19, 2022
Tracing instruction in lldb debugger.Just a python-script for lldb.

lldb-trace Tracing instruction in lldb debugger. just a python-script for lldb. How to use it? Break at an address where you want to begin tracing. Im

null 147 Sep 4, 2022
Visual Interaction with Code - A portable visual debugger for python

VIC Visual Interaction with Code A simple tool for debugging and interacting with running python code. This tool is designed to make it easy to inspec

Nathan Blank 1 Nov 16, 2021
An improbable web debugger through WebSockets

wdb - Web Debugger Description wdb is a full featured web debugger based on a client-server architecture. The wdb server which is responsible of manag

Kozea 1.6k Sep 18, 2022
PINCE is a front-end/reverse engineering tool for the GNU Project Debugger (GDB), focused on games.

PINCE is a front-end/reverse engineering tool for the GNU Project Debugger (GDB), focused on games. However, it can be used for any reverse-engi

Korcan Karaokçu 1.4k Oct 4, 2022
Little helper to run Steam apps under Proton with a GDB debugger

protongdb A small little helper for running games with Proton and debugging with GDB Requirements At least Python 3.5 protontricks pip package and its

Joshie 20 Aug 16, 2022
Full featured multi arch/os debugger built on top of PyQt5 and frida

Full featured multi arch/os debugger built on top of PyQt5 and frida

iGio90 1.1k Sep 27, 2022
Arghonaut is an interactive interpreter, visualizer, and debugger for Argh! and Aargh!

Arghonaut Arghonaut is an interactive interpreter, visualizer, and debugger for Argh! and Aargh!, which are Befunge-like esoteric programming language

Aaron Friesen 2 Dec 10, 2021
A simple rubber duck debugger

Rubber Duck Debugger I found myself many times asking a question on StackOverflow or to one of my colleagues just for finding the solution simply by d

null 1 Nov 10, 2021
Hdbg - Historical Debugger

hdbg - Historical Debugger This is in no way a finished product. Do not use this

Fivreld 2 Jan 2, 2022
Trashdbg - TrashDBG the world's worse debugger

The world's worse debugger Over the course of multiple OALABS Twitch streams we

OALabs 21 Jun 17, 2022
The official code of LM-Debugger, an interactive tool for inspection and intervention in transformer-based language models.

LM-Debugger is an open-source interactive tool for inspection and intervention in transformer-based language models. This repository includes the code

Mor Geva 96 Sep 19, 2022
Hunter is a flexible code tracing toolkit.

Overview docs tests package Hunter is a flexible code tracing toolkit, not for measuring coverage, but for debugging, logging, inspection and other ne

Ionel Cristian Mărieș 694 Sep 20, 2022
Trace any Python program, anywhere!

lptrace lptrace is strace for Python programs. It lets you see in real-time what functions a Python program is running. It's particularly useful to de

Karim Hamidou 686 Sep 18, 2022
Debugging manhole for python applications.

Overview docs tests package Manhole is in-process service that will accept unix domain socket connections and present the stacktraces for all threads

Ionel Cristian Mărieș 332 Aug 24, 2022