RunSnakeRunRunSnakeRun is a small GUI utility that allows you to view (Python) cProfile or Profile profiler dumps in a sortable GUI view.  It allows you to explore the profiler information using a "square map" visualization or sortable tables of data.  It also (experimentally) allows you to view the output of the Meliae "memory analysis" tool using the same basic visualisations.


RunSnakeRun is a simple program, it doesn't provide all the bells-and-whistles of a program like KCacheGrind, it's intended to allow for profiling your Python programs, and just your Python programs.  What it does provide, for profile viewing:

For Meliae memory-dump viewing, it provides:


You will need to have all of wxPython, SquareMap and RunSnakeRun installed to use RunSnakeRun.  You may also need the "python-profiler" package for your platform, which provides the pstats view.  You will likely want to use your platform wxPython package (i.e. a pre-built binary). For Debian/Ubuntu distributions the prerequisite setup looks like this:

apt-get install python-profiler python-wxgtk2.8 python-setuptools

RunSnakeRun and SquareMap will install well in a VirtualEnv if you would like to keep them isolated (normally you do not want to use the --no-site-packages flag if you are doing this).  I recommend this approach rather than using easy_install directly on your Linux/OS-X host.

virtualenv runsnake
source runsnake/bin/activate

If you already have Python setuptools installed (a.k.a. easy_install), you should be able to install the Python packages with:

easy_install SquareMap RunSnakeRun

You will require a modern wxPython (e.g. 2.8) and Python 2.x (e.g. 2.5 through 2.7) installation.  The setup will create a script named "runsnake" on Linux machines which launches the profile viewer.  On OS-X machines a wrapper script runsnake is created that runs the runsnake32 executable with a flag to tell Python to use the 32-bit implementation (for wxPython compatibility).  On Win32 machines, a Scripts\runsnake.exe executable is created.  If you have added your scripts directory to the PATH then this will be available from the command-line.


If you are new to profiling you may wish to check out:

cProfile Viewing

To use cProfile to capture your application's profile data, either using the command-line, like so:

$ python -m cProfile -o <outputfilename> <script-name> <options>

Or in code, like so:

import cProfile
command = """"""
cProfile.runctx( command, globals(), locals(), filename="OpenGLContext.profile" )

To view the results of your run:

python OpenGLContext.profile

There will be a brief delay as the application is created and begins the loading process, then you should see something like this:

Screenshot of the application viewing a HotShot profile

Click on any column title to sort by that property within that list.  Select a record in the left-most list view to see a breakdown of that record in the right-side list views.  Choose the appropriate view on the right via the tabs.  You can resize the borders between the lists and square-map views.  You can select a package/module/function hierarchic view via the menus.  You can also toggle use of percentage displays there.

Meliae Memory Analysis

Note: this feature is considered experimental, the memory consumed loading even a tiny meliae dump is enormous, so real-world programs will make RunSnakeRun quite slow and require a very large amount of RAM (far more than the process being viewed).

To install Meliae, you will need a working C extension compilation environment (Meliae uses a Cython extension):

easy_install meliae

Now instrument your application to be able to trigger a memory dump at the moment you would like to capture, like so:

from meliae import scanner
scanner.dump_all_objects( filename ) # you can pass a file-handle if you prefer

The memory dump will generally be quite large (e.g. 2MB to describe an application with 200KB of user-controllable memory usage (i.e. not the interpreter itself)) and for any real application will take an extremely long time to load (multiple minutes for 16MB dumps).

$ runsnakemem <filename>

Screenshot of a meliae memory view

The Meliae loader in RunSnakeRun performs the following simplifications:

Even with those simplifications, however, the program is tracking most ints, strings, tuples, lists, etc. separately, which uses a large amount of RAM and slows down the GUI substantially.

Code Access and Contributions

RunSnakeRun is reasonably stable.  I don't tend to do much work on it, as it tends to just work.  My (personal) current wish list for the project follows:

If you have an idea, feel free to check out the code and implement the new feature.  I'm certainly willing to entertain new features or bug-fix requests as well.  The code is available in bzr here:

bzr branch lp:~mcfletch/squaremap/trunk squaremap
cd squaremap
python develop
bzr branch lp:~mcfletch/runsnakerun/trunk runsnakerun
cd runsnakerun
python develop

You can contact me directly if you'd like to contribute.  Or you can just set up a bzr branch on LaunchPad and request a merge.


This is just a listing of things that either I or others have requested as features:

Other Tools

RunSnakeRun is by no means a comprehensive tool-set for profiling, you may want to have any or all of these other tools available for your profiling needs: