Process injection

ppTOP works in 2 modes: first is launching new Python program, ppTOP just reads its code, inserts pptop.inection module before, which wait for ready event (Ctrl+L) or for specified number of seconds (“-w” command line option).

The second mode is injecting into running Python process. When I created ppTOP, I was inspired by pyrasite which is pretty cool but unfortunately outdated, plus I wanted completely console UI.

ppTOP has 3 different but similar :) inject methods: native, loadcffi, unsafe. You may also specify auto method and ppTOP will try all 3, starting from native. Inject method can be specified in configuration (default is native) or set with “–inject-method” command line option.

If method is specified neither in configuration, nor in command line, auto is used.

All methods require gdb and of course an access to the process, so you must be root or launch ppTOP under the same user.


When working in native method, ppTOP injects a small C library, which does the rest. Officially supported and best method, usually works, if no - report an issue.


Calling PyRun_SimpleString Python method directly with gdb is very unstable and usually process get segmentation fault. Of course, ppTOP locks GIL before, but usually it doesn’t help. However, I’ve found that when certain libraries are loaded, it works fine.

So, before starting main injection code, ppTOP injects _cffi_backend shared library into process. Good news - if your program use requests, CFFI backend library is probably already loaded and you may even try using unsafe method for this process.

If you want to try this method, cffi must be installed. If not - install it with shell command:

pip3 install cffi


Lock GIL and call PyRun_SimpleString without any preparations and helpers. Run and pray.

Injecting into Python versions, older than 3.4

ppTOP tries to agree on pickle version protocol with injected process automatically. If it fails, use “-p” or “–protocol” command line options. Note that some plugins may not work.

Also, note that pickle protocols older than version 4, may be slow.