Skip to main content
v2026.11,986 entries · CC-BY 4.0

Jupyter Notebook Debugging: bug, %pdb and the Visual Debugger

Debug a Jupyter notebook with %debug, %pdb, breakpoint() or the JupyterLab visual debugger, with a decision table and a worked NaN example.

Written and maintained by CASRAI Editorial Board

Published · Last updated

On this page

To debug a Jupyter notebook, use the route that matches the failure: run %debug in the next cell after an exception to inspect it post-mortem, turn on %pdb on to open the debugger automatically on every exception, call breakpoint() to stop at a chosen line, or, in JupyterLab with a debugging-capable kernel such as ipykernel, switch on the bug icon, click the gutter to set a breakpoint and run the cell. All four are documented by the JupyterLab, IPython and Python projects, and each answers a different question.

This guide is for researchers and analysts whose analysis lives in notebooks. It maps the notebook debugger, the IPython magics and the standard pdb commands onto each other, shows a clearly synthetic worked example on a measurements table, and lists the errors that most often stop the debugger from working. Debugging is also a reproducibility habit: a bug you can locate and describe is one you can fix in a way a collaborator can re-run (see computational reproducibility).

Ask CASRAI · free to tryQuestion about this guide? Ask CASRAI answers with linked sources. 2 free questions a day, no account.

Ask your first question freeSubscribe

What notebook debugging is used for in research

Notebook analyses fail in two ways. The first is a loud failure: an exception and a traceback. The second is quiet: the code runs but a value is wrong, such as a column of NaN after a normalisation step. A debugger helps with both, because it lets you stop execution, look at the actual values of variables and move through the code one line at a time instead of adding print statements and re-running the cell.

Three tools cover almost all of this in Jupyter. The IPython magics %debug and %pdb work in a classic text interface and rely on Python’s built-in pdb debugger. The visual debugger in JupyterLab adds a bug icon, gutter breakpoints and side panels. The IPython %xmode magic does not stop execution but changes how much detail a traceback shows, which is often enough to find the problem without a debugger.

Jupyter notebook debug and Jupyter notebook debugger: the same task, different tools

Searches for “jupyter notebook debug” and “jupyter notebook debugger” usually mean one of two things: the visual debugger panel in JupyterLab, or the pdb-based magics that have been part of IPython for longer. The sections below treat them separately so you can pick one. The IPython project describes its own interactive shell, which the notebook kernel builds on, in the IPython guide on this site.

Which route to use: a decision table

The data table below compares the four routes by how you start them, whether a special kernel is required and what the official documentation says about each. Use this short version to choose before reading the steps.

  • The cell just raised an exception and you want to look around: run %debug in the next cell. The IPython documentation says that running it without an argument is post-mortem debugging and that it always works only on the last traceback that occurred.
  • You expect exceptions and want the debugger every time: run %pdb on. IPython can call the interactive pdb debugger after the traceback printout when an exception is triggered.
  • You want to stop at a known line before anything fails: add breakpoint() to the code, which the Python documentation presents as the replacement for import pdb; pdb.set_trace(), or use a gutter breakpoint in the JupyterLab debugger.
  • You want to see variables, the call stack and breakpoints in panels: use the JupyterLab visual debugger, which needs a kernel with debugging support.

Install or access the debugging tools

The text debuggers need nothing beyond what a notebook already has. pdb is part of the Python standard library, and the %debug and %pdb magics are part of IPython, which runs the standard Python kernel.

The visual debugger is different. The JupyterLab documentation states that a kernel with support for debugging is required. It lists xeus-python, xeus-robot, ipykernel and common-lisp-jupyter as kernels that provide it, and its conda example installs JupyterLab 3 or later together with ipykernel 6 or later. If the debugger icon is greyed out, the most likely cause is that the notebook is attached to a kernel that is not on that list. The debugger is available in JupyterLab as described at jupyterlab.readthedocs.io; for the Python kernel most researchers use, that means ipykernel.

Choose the kernel from the kernel picker in the notebook, then confirm that the bug icon in the upper-right corner of the notebook is enabled. If it is enabled, the kernel supports debugging.

Step-by-step: debugging a failing cell

Route 1: post-mortem with %debug

  1. Run the cell that fails and read the traceback.
  2. In a new cell, run %debug with no argument. IPython opens pdb at the point of the last traceback.
  3. Use w (where) to print the stack, u and d to move up and down frames, p name to print a value and l to list the source around the current line.
  4. Type q to quit. The pdb documentation notes that quitting aborts the program being executed.

The IPython documentation also describes a second mode in which %debug runs statements under the debugger, optionally with --breakpoint FILE:LINE (short form -b). From IPython 7.3 on, user variables are no longer expanded when running code this way.

Route 2: automatic debugging with %pdb

The IPython documentation gives the forms %pdb on, %pdb 1, %pdb off and %pdb 0, and says that calling it with no argument toggles the state. When it is on, an exception triggers the interactive pdb prompt after the traceback prints. The initial state comes from the InteractiveShell.pdb configuration option. Turn it off before running a long unattended notebook, because a prompt waiting for input will stop the run.

Route 3: a breakpoint in the code

Insert breakpoint() on the line where you want to stop and run the cell. The Python documentation says the built-in can be used instead of import pdb; pdb.set_trace(). Remove it before sharing the notebook, so collaborators do not hit an unexpected prompt. For an exception you already caught, pdb.pm() performs post-mortem debugging of the exception in sys.last_exc, and pdb.post_mortem(t=None) accepts a traceback.

Route 4: the JupyterLab visual debugger

  1. Open the notebook with a kernel that supports debugging and toggle the bug icon in the upper-right corner of the notebook on.
  2. Click in the gutter beside a line number to add a breakpoint.
  3. Run the cell. Execution stops at the breakpoint.
  4. Inspect the Variables, Call stack, Breakpoints and Kernel Sources panels, then use step into or continue to move on.

The documentation describes the panels this way. Variables shows the frame selected in the call stack, with a Locals and Globals dropdown and tree and table views. Rendering a variable in the main area needs kernel support. Call stack lets you navigate frames. Breakpoints lists them and lets you add or remove them while stopped. Kernel Sources opens a file when you click it, and Source is a read-only editor in the main area; a setting named Show Sources in Main Area can move it to the sidebar. Source views opened automatically close when the debugger steps into another file or the session ends, while views you opened by hand stay. A variable filter setting hides variables from both the tree and table views.

Output and how to read it

pdb commands and their visual-debugger counterparts

The Python documentation lists the pdb commands below. The table pairs each with the JupyterLab panel or action that does the same job, using the panel descriptions above. The JupyterLab page names only step into and continue as step actions, so the pairing is limited to those.

pdb command What the Python documentation says it does Visual-debugger counterpart
w (where) Prints the stack trace, most recent frame at the bottom Call stack panel
u / d [count] Moves up or down the stack Selecting a frame in the Call stack panel
b (break) Sets a breakpoint at a filename:lineno or function, with an optional condition Gutter click or Breakpoints panel
s (step) Executes the current line, stopping in a called function Step into
c (continue) Continues until the next breakpoint Continue
p expr / pp expr Prints or pretty-prints an expression Variables panel
l (list) Lists source around the current line Source panel
q (quit) Aborts the program being executed Ending the debug session

In pdb, a blank line repeats the last command, and h (help) lists what is available. Other commands such as n (next), r (return) and pp are documented on the same page.

Make tracebacks informative first with %xmode

Before opening a debugger, try %xmode Verbose. The IPython documentation lists the modes Plain, Context, Verbose, Minimal, Docs and Doctest, says that Verbose shows local variable values, and says that calling it with no argument cycles through the modes. For a failure inside a short function, the values printed in a verbose traceback often show the culprit immediately. You can also set __tracebackhide__ = True in a helper function so that frame is omitted from tracebacks, with the --show and --hide options controlling that behaviour.

Worked example: a NaN-producing normalisation

This example is an illustrative composite, not a real study. Suppose a notebook holds a measurements table with one row per sample and a numeric column named signal, and a function rescales each group to zero mean and unit variance:

def zscore(df):
    return (df['signal'] - df['signal'].mean()) / df['signal'].std()

df['z'] = df.groupby('batch', group_keys=False).apply(zscore)

The cell runs without an exception, but a later plot is empty because z contains NaN for some batches. There is no traceback, so post-mortem debugging has nothing to inspect. The right route is a breakpoint.

  1. Add breakpoint() as the first line of zscore and run the cell, or click the gutter beside that line in JupyterLab.
  2. When execution stops, print the frame’s data with p df['signal'].describe() or look in the Variables panel.
  3. Press c to continue to the next group and repeat. A batch with a single sample has no sample standard deviation to divide by, and the quotient is NaN; a batch where signal contains missing values propagates NaN in the same way.
  4. Fix the function to handle the cases you have found, remove the breakpoint and re-run the cell.

The point is the sequence, not the specific data: stop where the bad value is created rather than where it is noticed, check the inputs of the failing step, and only then change code.

Troubleshooting

  • The bug icon is disabled. The JupyterLab documentation says a kernel with debugging support is required. Switch to a kernel from its list, such as ipykernel.
  • %debug says there is nothing to debug. The documentation says the post-mortem mode works only on the last traceback that occurred, so run it immediately after the failing cell, not after a cell that succeeded.
  • Breakpoint never stops. Breakpoints in the visual debugger only stop when the cell containing that line is run with the debugger toggled on. Toggle it on before running.
  • A notebook hangs when run unattended. A leftover breakpoint() or %pdb on opens a prompt that waits for input. Remove them or run %pdb off.
  • Variables are missing in the Variables panel. A variable filter setting hides variables from both views; also check the Locals/Globals dropdown.
  • A source tab disappeared. Source views the debugger opened close when it steps into another file or the session ends; open the file manually from Kernel Sources to keep it.

All of the tools in this guide are free to use. The table lists where each is documented and what it needs.

Tool Where it runs Documented by
pdb Any Python code, including notebook cells Python documentation
%debug, %pdb, %xmode IPython and notebooks using the IPython kernel IPython documentation
Visual debugger JupyterLab with a debugging-capable kernel JupyterLab documentation

For notebooks run in a hosted environment, see the comparison of Google Colab and Jupyter Notebook. Editors with their own debuggers are covered in the guides to PyCharm and Positron. For notebook typesetting rather than debugging, see Jupyter Notebook LaTeX.

Frequently asked questions

How do I debug a Jupyter notebook?

Run %debug after an exception for post-mortem inspection, add breakpoint() to stop at a line, or use the JupyterLab visual debugger by toggling the bug icon and clicking the gutter to set a breakpoint. The visual debugger requires a kernel with debugging support.

How do I debug in a Jupyter notebook without a visual debugger?

Use pdb through IPython: %debug for the last traceback, %pdb on for automatic entry on exceptions, or breakpoint() in the code. Then use the pdb commands such as w, p, n, s and c.

Why is the Jupyter debugger icon greyed out?

According to the JupyterLab documentation, the icon is enabled only when the kernel supports debugging. Switch to a supported kernel such as ipykernel or xeus-python.

What is the difference between %debug and %pdb?

%debug opens the debugger on demand, either post-mortem on the last traceback or while running statements. %pdb on makes IPython open the debugger automatically each time an exception is raised.

Can I see variable values without stopping the code?

Yes. %xmode Verbose makes tracebacks show local variable values, which can be enough to find a bug without entering the debugger.

Sources

Data: Jupyter notebook debugging routes compared

Original comparison of four ways to debug a Jupyter notebook (the %debug magic, the %pdb magic, breakpoint(), and the JupyterLab visual debugger), compiled from the JupyterLab, IPython and Python pdb documentation: how each is started and what the documentation says about kernel requirements and when it applies.

Jupyter notebook debugging routes compared
RouteHow it is startedKernel requirement stated in documentationWhen it applies
%debug (post-mortem)Run %debug with no argument in the cell after an exceptionNone beyond IPythonWorks only on the last traceback that occurred
%pdb onRun %pdb on (or 1); %pdb off or 0 to disable; no argument togglesNone beyond IPythonOpens pdb after the traceback when an exception is triggered
breakpoint()Add the call to the code and run the cellNone (Python built-in)Stops at a chosen line; documented as the replacement for import pdb; pdb.set_trace()
JupyterLab visual debuggerToggle the bug icon, click the gutter to set a breakpoint, run the cellA kernel with debugging support (xeus-python, xeus-robot, ipykernel, common-lisp-jupyter)Stops at gutter breakpoints; shows variables, call stack, breakpoints and sources in panels

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about Jupyter Notebook Debugging: bug, %pdb and the Visual Debugger

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →