Visualize Execution

Python Tutor is designed to imitate what an instructor in an introductory programming class draws on the blackboard:

Instructors use it as a teaching tool, and students use it to visually understand code examples and interactively debug their programming assignments.

Quick links:

• Documentation and unsupported features
• FAQ for instructors using Python Tutor
• How the Python Tutor visualizer can help students in your Java programming courses
• How the Python Tutor visualizer can help students in your C or C++ courses

Demo

The screenshot below shows how a typical user (either an instructor or a student) would interact with it:

• (1) Go to pythontutor.com and select a language. Here the user chose Java and wrote code to recursively create a LinkedList.
• (2) Press ‘Visualize’ to run the code. This code ran for 46 steps, where each step is one executed line of code. Go to any step (2a) and see what line of code was being run at that step (2b).
• (3) See the frames of all functions/methods on the stack at this step, each of which shows its local variables. Here at step 41 we see main() along with 4 recursive calls to init().
• (4) See all objects on the heap at the current step. Here it shows a LinkedList instance with first and last fields pointing to its first and last Node instances, respectively. Each Node has a numerical value and a next pointer.
• (5) See what has been printed up to this step. Here the print statement in the Node constructor (line 5) has run 3 times.

The user can navigate forwards and backwards through all execution steps, and the visualization changes to match the run-time state of the stack and heap at each step. In this example, the user would see their custom LinkedList data structure getting incrementally built up one Node at a time via recursive calls to init() until the base case is reached when n==0.

Language Support

Despite its name, Python Tutor is also a widely-used web-based visualizer for Java that helps students to understand and debug their code. It visualizes the majority of object-oriented programming concepts taught in introductory college courses (e.g., CS1 and CS2), high school AP Computer Science, and intermediate-level Java programming.

Python Tutor is also a widely-used web-based visualizer for C and C++ meant to help students in introductory and intermediate-level courses. It uses Valgrind to perform memory-safe run-time traversal of data structures, which lets it display data more accurately than gdb or printf debugging. For instance, it can precisely visualize critical concepts such as pointers, uninitialized memory, out-of-bounds errors, nested arrays/structs/unions, type punning, and bit manipulation.

Lastly, it also supports visualizing standalone JavaScript execution, but not web frontend code that does DOM manipulation on webpages.

Unsupported Features

Recall that Python Tutor is designed to imitate what an instructor in an introductory programming class draws on the blackboard:

Thus, it is meant to illustrate small pieces of self-contained code that runs for not too many steps. After all, an instructor can't write hundreds of lines of code, draw hundreds of data structures and pointers, or walk through hundreds of execution steps on the board! Also, code in introductory classes usually doesn't access external libraries. If your code can't fit on a blackboard or presentation slide, it's probably too long to visualize effectively in Python Tutor. This tool is not meant as a professional-level debugger.

Due to this ultra-focused design, the following features are not supported on purpose:

• Code that is too large in size
  • shorten your code to what fits on a blackboard or presentation slide
  • Python Tutor is not for debugging arbitrary code that you paste into it; you'll need to shorten your code to isolate what you want to debug
• Code that runs for too many steps (e.g., > 100) or for a long time (e.g., > 10 sec)
  • shorten your code to isolate exactly what operations you want to visualize
  • e.g., make your numbers/strings smaller, arrays/lists shorter, your data structures contain fewer items, and your loops/functions run fewer times
  • for Python, set breakpoints using special #break comments (example)
• Code that defines too many variables or objects
  • shorten your code to isolate what variables you want to visualize
  • remove unnecessary variables and objects from your code
  • for Python, use #pythontutor_hide to selectively hide objects (example)
  • also use “Move and hide objects” option at bottom-left of visualizer to hide
• Advanced language features or subtleties that only experts need to know about
• Importing most external libraries (it’s meant for learning basic coding concepts)
• Visualizing custom data structures from libraries (it supports only built-in types)
• Interfacing with files, databases, networking, or other external resources
• Anything involving GUI programming or manipulating GUI/webpage components
• Multi-threaded / concurrent / asynchronous code (only supports single-threaded)

Other general unsupported features:

• Command-line arguments (e.g., argv[]) not supported; use hard-coded strings instead
• Reading data from external files is not supported (workaround: use strings to emulate files. StringIO examples for Python3 and Python2)
• You cannot step within a line of code to show how subexpressions get evaluated within that line; the best workaround is to manually split complex expressions into multiple lines and assign to temporary variables on each line (example).
• Printing to stderr probably won’t work; use print statements to print to stdout
• Some Unicode characters may not display if your browser doesn’t have those fonts or if you’re trying to print unprintable characters like binary data to terminal
• This tool uses slightly older versions of languages (e.g., Python 3.6) for greater stability and because instructional materials often rely on older versions. Upgrading to the newest versions can confuse beginners who are learning from instructional materials since the compiler/interpreter messages do not match their materials.

For a detailed list of unsupported features for each programming language, view the full documentation here.

Reporting Bugs

The issue you’re encountering is likely listed in this document. If you're sure it's not, use the "Generate permanent link" button to make a URL of your code. Describe the expected behavior when running that code on your computer and how it differs from Python Tutor, then fill out this Google Form to report your bug or security issue.

• This form is not for requests or questions about desired features; it is only for reproducible bug reports and private disclosures of security-related issues.
• If you don't get a reply, assume your issue will not be addressed. Please do not submit duplicate issues in the form.
• There is no support for Python Tutor visualizations that are embedded in other people’s websites. Contact those site owners for help on how to use their sites.