1. Xavier de Gaye
  2. pdb-clone


Clone wiki

pdb-clone / Home


A clone of pdb, fast and with the remote debugging and attach features.

pdb-clone features:

  • Implement the most recent Python 3 features of pdb, as defined in the Python 3 pdb documentation. The pdb command line interface remains unchanged except for the new detach and thread pdb commands.

  • Improve significantly pdb performance. With breakpoints, pdb-clone runs just below the speed of the interpreter while pdb runs 10 to 100 times slower than the interpreter, see Performances.

  • Extend pdb with remote debugging. A remote debugging session may be started when the program stops at a pdb.set_trace_remote() hard-coded breakpoint, or at any time and multiple times by attaching to the process main thread. See RemoteDebugging.

  • Fix pdb long standing bugs entered in the Python issue tracker, see the NEWS.

  • Add a bdb comprehensive test suite (more than 70 tests) and run both pdb and bdb test suites.

pdb-clone runs the same source code on all the supported versions of Python, which are:

  • Python 3: from version 3.2 onward.

  • Python 2: version 2.7.


Invoke pdb-clone as a script to debug other scripts. For example:

$ pdb-clone myscript.py

Or use one of the different ways of running pdb described in the pdb documentation and replace

import pdb


from pdb_clone import pdb

or with

import pdb_clone.pdb as pdb

So, for example, to hard-code a breakpoint at a given point in a program:

import pdb_clone.pdb as pdb; pdb.set_trace()


Install with pip

pdb-clone is at PyPi.

To install pdb-clone with pip:

$ sudo pip install pdb-clone

Installation from source

Download the tarball from PyPi.

Untar the archive, change directory to the distribution directory and run the setup script to install pdb-clone:

$ tar xzf pdb-clone-d.d.tar.gz
$ cd pdb-clone-d.d
$ python setup.py install

The installation process builds the _bdb C extension module and requires some Python header files. You may need to install a python-dev package for the build to succeed. On debian systems this is done with:

$ aptitude install build-essential python-dev

You don't need to install anything when you have built and installed Python from source.

When building of the _bdb extension module fails, the install process prints a warning and pdb-clone falls back on running a Python implementation of the _bdb extension module. In that case, the build of the pdbhandler extension module will also probably fail, and running pdb-attach --pid PID will fail with the following error message:

ImportError: No module named pdb_clone.pdbhandler

The first line printed by the pdb-clone script states wether it is running with the _bdb extension module or not.

Local installation

Use a local installation when you do not have root privileges and those are required to install Python packages. Local installation is done using the user scheme:

$ pip install --user pdb-clone


$ python setup.py install --user

Build a source distribution

First, the wiki repository must be cloned in pdb-clone root directory (pdb-clone.wiki must be a subdirectory of the root directory).

For example, to build a source distribution:

$ python setup.py sdist

Test suite

The test suite is run against the installed version of pdb_clone, not against the developpement version. To run all the tests, first install pdb_clone and then run the following command from the root directory:

$ python setup.py test

To get help on the available test options:

$ python setup.py test --help

For example, to obtain the verbose output of all the pdb tests whose name starts with test_issue14, while stopping at the occurence of the first test failure:

$ python setup.py test --tests=pdb --detail --prefix=test_issue14 --stop


Use the issue tracker to report bugs or to request new features.

When reporting bugs, please indicate pdb-clone version and wether it is running with _bdb. The first line printed by the pdb-clone script prints pdb-clone version and states wether it is running with the _bdb extension module or not.

When running pdb-clone from the Python interpreter:

  • pdb_clone.__version__ is pdb-clone version.

  • The value of bdb.Bdb.__bases__ is <class '_bdb.BdbTracer'>, when pdb-clone runs with the _bdb extension module.


This software is licensed under the terms you may find in the file named LICENSE in this directory.

Copyright © 2001-2012 Python Software Foundation; All Rights Reserved. pdb-clone is a derivative work of a part of Python and as such, subject to the Python license.