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.
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
%debugin 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 forimport 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
- Run the cell that fails and read the traceback.
- In a new cell, run
%debugwith no argument. IPython opens pdb at the point of the last traceback. - Use
w(where) to print the stack,uanddto move up and down frames,p nameto print a value andlto list the source around the current line. - Type
qto 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
- Open the notebook with a kernel that supports debugging and toggle the bug icon in the upper-right corner of the notebook on.
- Click in the gutter beside a line number to add a breakpoint.
- Run the cell. Execution stops at the breakpoint.
- 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.
- Add
breakpoint()as the first line ofzscoreand run the cell, or click the gutter beside that line in JupyterLab. - When execution stops, print the frame’s data with
p df['signal'].describe()or look in the Variables panel. - Press
cto 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 wheresignalcontains missing values propagates NaN in the same way. - 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.
%debugsays 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 onopens 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.
Free alternatives and related environments
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
- JupyterLab documentation, Debugger: https://jupyterlab.readthedocs.io/en/stable/user/debugger.html (read 2026-11-14)
- IPython documentation, Built-in magic commands: https://ipython.readthedocs.io/en/stable/interactive/magics.html (read 2026-11-14)
- Python documentation, pdb, the Python debugger: https://docs.python.org/3/library/pdb.html (read 2026-11-14)
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.
| Route | How it is started | Kernel requirement stated in documentation | When it applies |
|---|---|---|---|
| %debug (post-mortem) | Run %debug with no argument in the cell after an exception | None beyond IPython | Works only on the last traceback that occurred |
| %pdb on | Run %pdb on (or 1); %pdb off or 0 to disable; no argument toggles | None beyond IPython | Opens pdb after the traceback when an exception is triggered |
| breakpoint() | Add the call to the code and run the cell | None (Python built-in) | Stops at a chosen line; documented as the replacement for import pdb; pdb.set_trace() |
| JupyterLab visual debugger | Toggle the bug icon, click the gutter to set a breakpoint, run the cell | A 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
- JupyterLab documentation: Debugger (accessed 2026-11-14)
- IPython documentation: Built-in magic commands (accessed 2026-11-14)
- Python documentation: pdb (accessed 2026-11-14)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







