Refs: #126431, microsoft/vscode-jupyter#6207, microsoft/vscode-jupyter#6376, microsoft/vscode-jupyter#6215

• macOS @alexdima
• linux @lramos15
• windows @meganrogge

Note: Please file bugs here

Complexity: 5

Authors: @roblourens, @DavidKutu, @IanMatthewHuff, @rchiodo

Create Issue

Setup

Note: The jupyter extension won't be updated in the marketplace until around noon Zurich time Tuesday, so wait to test this until then.

• Make sure that you have python 3 installed and on your path as python3 or python
• Set up a python virtualenv (use regular python, conda is not supported yet)

mkdir jupyter-dbg
cd jupyter-dbg
python3 -m venv ipykernel-env

• Activate the virtual environment

Mac/Linux:

source ipykernel-env/bin/activate

Windows:

ipykernel-env\Scripts\activate.bat

• Install the latest version of ipykernel in the virtual environment, which has debugging support

pip install ipykernel --pre
python3 -m ipykernel install --user

• Make sure you have the latest version of the Jupyter extension installed in VS Code Insiders
• (the bits should be in the marketplace on Tuesday 29th at 2:40am-2:50am Redmond time or 11:40am-11:50am Zurich time)
• The current insiders version is: v2021.7.978384885 so you will need a version past that.

Hit a breakpoint

• Launch VS Code, open jupyter-dbg
• Set the experiment setting to enable jupyter debugging "jupyter.experimental.debugging": true
• Open a .ipynb notebook file
• Pick a kernel, make sure you pick the venv kernel where you installed ipykernel

Should look something like this

If you don't see that entry, you may have to reload the window

• Click the Debug button in the notebook toolbar to start a debug session
  
  If the button doesn't appear, switch to another notebook and switch back, this is a known issue

  • You can also run the "Jupyter: Debug" command

• The breakpoint margin should appear

• If you set a breakpoint and run a cell, you should hit that breakpoint

More testing

• Note: the flow above is the only entrypoint to debugging. launch.json is not relevant here.
• Test all debugger features. Debug console, callstack, variables, breakpoints, conditional bps, etc
• Stepping between cells. Define a function in one cell, call from another cell
• Stepping from a notebook to a .py file
• Stepping from one cell to another. Run all cells, then if you "step over" from cell 1, you should land in cell 2
• Test debugging an untitled notebook
• You should never see an error that looks something like "Unable to open ..." with some tmp file path
• Test debugging in two notebooks simultaneously
• The debug button should not appear if you select a kernel that doesn't have ipykernel 6
• Ending the debug session should hide the breakpoint margin

Known issues

• The debug button takes a second to appear on notebook with valid kernels, it will be cached for the final release.
• The only event that triggers the check to enable the debug button is onDidChangeActiveNotebookEditor. If it doesn't appear, switch to another notebook and switch back.
• If your notebook was already open when VS Code is launched, the debug button won't appear.
• If you change the kernel to another one that doesn't support debugging, the button doesn't disappear and vice versa.
• Conda environments are not supported yet.
• A bunch of ipykernel_XXXX folders will appear on C:\Users\<user>\AppData\Local\Temp. Those should be deleted by the extension.
• The stop cell button should be disabled when debugging.