SnakeViz

Warnings

• gotcha SnakeViz is primarily designed to work with profile data generated by Python's `cProfile` module. It does not support output from the older `profile` module.
  Fix: Always use `cProfile` for generating profile data (e.g., `python -m cProfile -o output.prof my_script.py`).
• gotcha For very large or complex profile files, SnakeViz may struggle to create a visualization, sometimes displaying an error. This is due to the complexity of rendering an extremely large call tree.
  Fix: To mitigate this, try increasing the 'cutoff' value, reducing the 'depth' of the visualization, or profile a smaller, more focused subsection of your code. You can also manually navigate the stats table if the visualization fails.
• gotcha `cProfile`'s data format does not always allow a perfect reconstruction of the exact call stack and time spent, especially when the same function is called multiple times from different parts of the code. This can sometimes lead to slightly counter-intuitive visualizations.
  Fix: Be aware of this limitation when interpreting results, particularly with highly recursive or complex call patterns. Focus on the overall time distribution and major bottlenecks rather than micro-analyzing every single call path.
• breaking Official support for Python 2.7 has been dropped. While older versions (v2.1.2 and earlier) might still function, newer versions (2.2.0+) are built for Python 3.9+.
  Fix: Upgrade your Python environment to 3.9 or newer to ensure compatibility and receive updates. If Python 2.7 is strictly required, pin SnakeViz to a version `<=2.1.2`.
• gotcha When running SnakeViz via IPython magics outside of a Jupyter Notebook environment (e.g., in a terminal IPython session), the visualization will open in a new browser tab by default. Within Jupyter, it typically embeds in the notebook.
  Fix: Use the `--new-tab` or `-t` option with `%snakeviz` magic if you prefer to always open in a new tab, even in Jupyter. If working offline, save a profile file and use the command-line interface as IPython magics require internet access.

Install

• pip install snakeviz Install with pip

Imports

• Command Line

  snakeviz program.prof

  SnakeViz is primarily used as a command-line tool to visualize a profile file (e.g., generated by `python -m cProfile -o program.prof my_script.py`).
• IPython Magic

  %load_ext snakeviz
  %snakeviz my_function()

  While `snakeviz` is a Python package, its core visualization functionality is invoked via a command-line executable or IPython magics, not typically by direct Python `import` statements for user-facing visualization functions. Attempting `import snakeviz` for visualization is not the standard use case.

Quickstart

This quickstart demonstrates how to profile a Python function using the built-in `cProfile` module and then visualize the generated profile data with SnakeViz from the command line. For Jupyter/IPython, use the `%snakeviz` magic after loading the extension.

# 1. Profile your Python script using cProfile
import cProfile
import time

def waste_time():
    sum(range(1000000))

def main():
    for _ in range(5):
        waste_time()

cProfile.runctx('main()', globals(), locals(), 'output.prof')

# 2. Open the profile in SnakeViz from your terminal
#    (Run this in your shell, not in Python directly)
# !snakeviz output.prof