Skip to content
This repository has been archived by the owner on Jan 26, 2022. It is now read-only.


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.
Latest commit message
Commit time
December 10, 2020 15:24
July 30, 2020 14:37
November 19, 2020 11:04
May 15, 2020 13:36
July 8, 2020 15:54
October 17, 2019 16:04
August 8, 2019 12:32
September 3, 2019 14:33
July 19, 2019 14:19
October 12, 2020 13:31
December 10, 2020 15:24
December 20, 2019 10:46
December 13, 2020 00:43



This project is archived. Development is now happening in

If you use JupyterLab 3.x:

The debugger extension is shipped by default with JupyterLab 3.x and doesn't need to be installed manually.

Be sure to install a kernel that supports debugging, such as xeus-python:

conda install -c conda-forge xeus-python

Refer to the documentation for more details:

Please open new issues and pull requests on the JupyterLab repo:

If you use JupyterLab 2.x:

Follow the instructions below.

Github Actions Status Binder

A JupyterLab debugger UI extension. This extension is under active development.



  • JupyterLab 2.0+
  • xeus-python 0.8.0+
  • notebook 6+


A kernel with support for debugging is required to be able to use the debugger.

It is generally recommended to create a new conda environment to install the dependencies:

conda create -n jupyterlab-debugger -c conda-forge xeus-python=0.8.6 notebook=6 jupyterlab=2 ptvsd nodejs
conda activate jupyterlab-debugger

Then, run the following command to install the extension:

jupyter labextension install @jupyterlab/debugger


For now xeus-python is the only Jupyter kernel that supports debugging. xeus-python can be selected from the JupyterLab launcher:


Alternatively, it is also possible to switch to the xpython kernel using the kernel selection dialog:


Enable the debugger, set breakpoints and step into the code:



# Create a new conda environment
conda create -n jupyterlab-debugger -c conda-forge nodejs xeus-python=0.8.6 ptvsd jupyterlab=2

# Activate the conda environment
conda activate jupyterlab-debugger

# Install dependencies

# Build TypeScript source
jlpm build

# Link your development version of the extension with JupyterLab
jupyter labextension link .

# Rebuild TypeScript source after making changes
jlpm build

# Rebuild JupyterLab after making any changes
jupyter lab build

# Start JupyterLab with the kernel logs enabled and watch mode enabled
XEUS_LOG=1 jupyter lab --no-browser --watch


To run the tests:

# [Optional] to enable the logs for xeus-python
export XEUS_LOG=1

jlpm run test

To run tests for a specific test suite name:

jlpm run test --testNamePattern=<regex>

To run tests for a specific test module name:

jlpm run test --testPathPattern=<regex>

Inspecting debug messages

The kernelspy extension for JupyterLab can be used to inspect the debug messages sent between the debugger UI and the kernel.

To install it:

jupyter labextension install jupyterlab-kernelspy

Debug Protocol Overview

The following diagram illustrates the types of messages sent between the JupyterLab extension and the kernel.





Generated using:

Diagram source
user->JupyterLab: open notebook

JupyterLab->JupyterLab: check 'debugger' key\nin the kernel spec

JupyterLab->user: show toggle button\nif 'debugger'

user->JupyterLab: enable debugging

JupyterLab->kernel: debugInfo request

kernel->JupyterLab: debugInfo response

user->JupyterLab: start debugger

JupyterLab->kernel: initialize request

kernel->JupyterLab: initialize response

JupyterLab->kernel: attach request

kernel->JupyterLab: attach response

Note right of kernel: debugger started

user->JupyterLab: add breakpoints\n(click on gutters)

JupyterLab->kernel: dumpCell request

kernel->JupyterLab: dumpCell response

JupyterLab->kernel: setBreakpoints request

kernel->JupyterLab: breakpoints response

JupyterLab->kernel: configurationDone request

kernel->JupyterLab: configurationDone response

user->JupyterLab: execute cell\n(Ctrl-Enter)

JupyterLab->kernel: requestExecute

kernel->kernel: execute code

kernel->kernel: hit breakpoint

kernel-->JupyterLab: stopped event

JupyterLab->kernel: stackTrace request

kernel->JupyterLab: stackTrace response

JupyterLab->user: show current line

JupyterLab->kernel: scopes request

kernel->JupyterLab: scopes response

JupyterLab->kernel: variables request

kernel->JupyterLab: variables response

JupyterLab->user: show variables

user->JupyterLab: step in deleted cell code

JupyterLab->kernel: stepIn request

kernel-->JupyterLab: stopped event

JupyterLab->JupyterLab: search for code matching\nsource path

JupyterLab->kernel: source request

kernel->JupyterLab: source response

JupyterLab->user: show source for current path

Note right of kernel: debug session

user->JupyterLab: disable debugging

JupyterLab->kernel: disconnect request

Note right of kernel: debugger stopped

kernel->JupyterLab: disconnect response

JupyterLab->JupyterLab: clear debugger UI for\nthe notebook

Inspecting Debug Messages in VS Code

Inspecting the debug messages in VS Code can be useful to understand when debug requests are made (for example triggered by a UI action), and to compare the behavior of the JupyterLab debugger with the Python debugger in VS Code.

Create launch.json

The first step is to create a test file and a debug configuration:


  "version": "0.2.0",
  "configurations": [
      "name": "Python: Current File",
      "type": "python",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "env": { "DEBUGPY_LOG_DIR": "/path/to/logs/folder" }

Start the debugger


Open the logs

The content of the log file look like this:


D00000.032: IDE --> {
                "command": "initialize",
                "arguments": {
                    "clientID": "vscode",
                    "clientName": "Visual Studio Code",
                    "adapterID": "python",
                    "pathFormat": "path",
                    "linesStartAt1": true,
                    "columnsStartAt1": true,
                    "supportsVariableType": true,
                    "supportsVariablePaging": true,
                    "supportsRunInTerminalRequest": true,
                    "locale": "en-us"
                "type": "request",
                "seq": 1