Debugger#

JupyterLab ships with a Debugger front-end by default.

This means that notebooks, code consoles and files can be debugged from JupyterLab directly!

Requirements#

For the debugger to be enabled and visible, a kernel with support for debugging is required.

Here is a list of kernels that are known to be supporting the Jupyter Debug Protocol:

Other Jupyter Kernels can also support debugging and be compatible with the JupyterLab debugger by implementing the Jupyter Debugger Protocol.

If you know of other kernels with support for debugging, please open a PR to add them to this list.

Here is an example of how to install ipykernel and xeus-python in a new conda environment:

conda create -n jupyterlab-debugger -c conda-forge jupyterlab=3 "ipykernel>=6" xeus-python
conda activate jupyterlab-debugger

Usage#

Here is a screencast to enable the debugger and set up breakpoints. The various steps are described more in depth below.

A GIF showing how to enable the debugger within the kernel.

Use a kernel supporting debugger#

First, you will need to check that the kernel supports debugging. If so, the bug icon in the upper-right corner of the notebook will be enabled.

../_images/debugger-kernel.png

Debug code in notebook#

Now let’s enable the debugger for this notebook. The debugger can be enabled by toggling the bug button on in the upper-right corner of the notebook:

../_images/debugger-activate.png

Once debugging has been enabled, we can set breakpoints and step into the code.

Let’s define a function that adds two elements:

def add(a, b):
   res = a + b
   return res

We can call the function and print the result:

result = add(1, 2)
print(result)

Now let’s go back to the first code cell and click on the gutter on line number 2 to add a breakpoint:

../_images/debugger-breakpoint.png

Then let’s execute the second code cell by clicking on the _Run_ button:

../_images/debugger-run.png

The execution stops where the breakpoint is set:

../_images/debugger-stop-on-breakpoint.png

Explore the code state#

Exploring the code state is done with the debugger sidebar. It shows a variable explorer, a list of breakpoints, a source preview and the possibility to navigate the call stack.

../_images/debugger-sidebar.png

Variables

Variables can be explored using a tree view and a table view:

../_images/debugger-variables.png

Call stack

You can step into the code, and continue the execution using the debug actions:

../_images/debugger-callstack.png

Breakpoints

New breakpoints can be added and removed while the execution is stopped, and they will be shown in the list of breakpoints:

../_images/debugger-breakpoints.png

Source

The source panel shows the source of the current file being debugged:

../_images/debugger-source.png

If the source corresponds to a cell that has been deleted, clicking on the Open in Main Area button will open a read-only view of the source.