Skip to content


Folders and files

Last commit message
Last commit date

Latest commit



97 Commits

Repository files navigation


Tests (GitHub Actions) PyPI Supported Python Versions PyPI version GitHub license

A fully-featured remote debugger for python.

  • Provides a full remote tty, allowing sending keyboard signals to the debugger, tab completion, command history, line editing and more
  • Runs the IPython debugger with all its capabilities
  • Allows attaching to running programs preemptively (does not require gdb, unlike similar tools)
  • Affects the debugged program minimally, although not yet recommended for use in production environments
  • Provides TTY features even when debugged program is a deamon, or run outside a terminal


pip install madbg


Madbg provide both a python API and a CLI.

Attaching to a running process

madbg attach <pid>


import madbg


  • Attaching on linux could potentially deadlock the target process. Not recommneded for use in production environments yet.
  • madbg has to be installed in the target process' interpreter for attach to work.

Starting a debugger

Using the CLI

Run a python file with automatic post-mortem:

madbg run <args_for_script ...>

Run a python module similarly to python -m:

madbg run -m <args_for_script ...>

Start a script, starting the debugger from the first line:

madbg run --use-set-trace <args_for_script ...>

Using the API

Start a debugger in the next line:


Continue running the program until a client connects, then stop it and start a debugger:


After an exception has occurred, or in an exception context, start a debugger in the frame the exception was raised from:


Connecting to a debugger

Using the CLI

madbg connect

Using the API



All madbg API functions and CLI entry points allow using a custom IP and port (the default is, for example:

madbg.set_trace(ip='', port=1337)


madbg connect 1337


Madbg supports linux with python>=3.7.

Possible effects

What madbg does that might affect a debugged program:

  • Changes the pgid and sid of the debugged process
  • Changes the CTTY of the debugged process
  • Affects child processes in unknown ways (Not tested yet)

What madbg doesn't do:

  • Writes or reads from stdio
  • Feeds your cat