Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 39 ยท Notebooks and Kernels

Restart, Interrupt and Debug

Handle stuck cells and dead kernels in Jupyter: interrupt versus restart, reading tracebacks, post-mortem debugging with %debug, the visual debugger, and freeing memory.

Sooner or later a cell runs forever, the kernel "dies", or an exception scrolls past with a wall of red text. Knowing which button to press, and how to read what the kernel tells you, turns these moments from panic into routine. This lesson covers the three tools you need: interrupt, restart and debugging.

Real kernels are not available on this site. The stand-ins reproduce the same Python behaviours (tracebacks, KeyboardInterrupt, memory use) with ordinary code, and the Jupyter-specific commands are shown read-only.

A cell that never finishes

Symptoms: the prompt shows [*], the kernel indicator is filled (busy), and your later cells queue behind it. Reasons include an infinite loop, a huge computation, a network call without a timeout, or a program waiting for input.

Your options, from gentlest to harshest:

  1. Interrupt (the square Stop button, Kernel โ†’ Interrupt Kernel, or I I in command mode). It raises KeyboardInterrupt inside your code. Memory is preserved, so you keep your data. Pure-Python loops stop quickly; code stuck in a C extension may ignore the interrupt until it returns.
  2. Restart (Kernel โ†’ Restart Kernel, or 0 0). The process is killed and re-created. You lose all variables, but it always works.
  3. Shut down and re-open the notebook, if the front end itself is confused.

The stand-in below mimics an interrupted loop. The loop keeps its partial result, which is exactly what you can inspect after pressing Stop:

Python Stand-in: an interrupted loop keeps its partial state

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

To avoid endless runs, put limits into long cells: a maximum number of loop iterations, a timeout argument on network calls (for example requests.get(url, timeout=10)), and a progress indicator so you can see movement (covered with tqdm in the visualization chapter).

Dead kernels

Sometimes a dialog says "The kernel appears to have died. It will restart automatically." The process stopped without you asking. The two most common causes:

  • Out of memory. The operating system killed the process because it used too much RAM (a huge DataFrame, a Cartesian join, loading a giant file).
  • Crash in native code (a bug in a compiled library) or a segmentation fault.

After an automatic restart your variables are gone. Read the terminal where the server runs: it often prints the reason. To prevent repeats, work with a sample of the data while developing, free big objects with del, process files in chunks, and check memory use (see below).

Reading a traceback

When a cell raises an exception, the notebook prints a traceback. Read it from the bottom up: the last line names the error and its message; the lines above show the chain of calls that led to it, with the cell number and line.

Text
---------------------------------------------------------------------------
ZeroDivisionError                         Traceback (most recent call last)
Cell In[4], line 5
      2     return total / count
----> 5 average([])
...
ZeroDivisionError: division by zero

The arrow ----> marks the line that failed. IPython's tracebacks add context lines and colours. The %xmode magic switches the detail level (Plain, Context, Verbose, Minimal).

Python Stand-in: find the failing line in a traceback

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Post-mortem debugging with %debug

After an exception, you can open the Python debugger at the point of the error, without re-running anything. In the next cell type:

Python
%debug

An interactive ipdb> prompt appears, with the frame where the exception happened. Useful commands:

Command Action
p expr or just the name Print a value
l List source code around the line
u / d Move up or down the call stack
w Show the call stack
q Quit the debugger

To drop into the debugger automatically whenever an error happens, run %pdb on (turn it off with %pdb off). You can also stop at a chosen line by calling breakpoint() in your code. These commands need an interactive input box, which is why they are shown read-only here.

The visual debugger

JupyterLab (with ipykernel 6 or later, which includes the Debug Adapter Protocol through debugpy) offers a graphical debugger:

  1. Open the Debugger panel from the right sidebar (the bug icon), or click the bug icon in the notebook toolbar to turn debugging on.
  2. Click in the gutter next to a line number to set a breakpoint.
  3. Run the cell. Execution stops at the breakpoint.
  4. Use the panel to see Variables, the Call Stack, step over, step into, continue.

Not every kernel supports it (it needs a kernel that implements the debugger protocol, which ipykernel does).

The oldest tool: print debugging

Often the quickest way is to display intermediate values. In a notebook this is especially convenient because the last expression of a cell displays itself. Add a temporary cell that shows the suspicious variable, or use display().

Looking at memory

Out-of-memory problems start with not knowing what is big. IPython provides %whos, which lists variables with their type and size information. The stand-in prints a simple version of it using plain Python:

Python Stand-in: a mini %whos with memory sizes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Note that sys.getsizeof is shallow: it does not count the objects inside a list. Libraries such as pandas give better numbers (df.memory_usage(deep=True)).

A short recovery checklist

  1. Cell hangs: Interrupt. Still stuck: Restart.
  2. Error: read the last line of the traceback first, then the failing line.
  3. Need to inspect state at the error: %debug.
  4. Dead kernel: check memory and the server terminal log.
  5. After any restart: Run All to rebuild state, which also tests your notebook (see Execution order and hidden state).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does Interrupt do compared to Restart?

    Interrupt stops the running code but keeps kernel memory; Restart starts a new process with empty memory.
  2. 2. In which direction should you read a Python traceback first?

    The last line gives the exception type and message; the lines above show how execution got there.
  3. 3. Which magic opens the debugger after an exception already happened?

    %debug starts post-mortem debugging at the most recent exception.
  4. 4. A kernel dies with no Python error. What is the first likely suspect?

    The operating system often kills a process that uses too much RAM, and the kernel disappears without a traceback.

Summary

  • Interrupt stops running code and keeps variables; Restart clears everything and always works.
  • Add limits and timeouts to long cells so you rarely need either.
  • Dead kernels usually mean memory exhaustion or a native crash; read the server terminal.
  • Read tracebacks bottom-up; %xmode changes their detail.
  • %debug, %pdb on and breakpoint() give post-mortem and live debugging; JupyterLab adds a visual debugger.
  • Watch memory with %whos and del large objects you no longer need.

Next: Cell types and Markdown