Use the Databricks interactive debugger

Preview

This feature is in Public Preview.

This page describes how to use the built-in interactive debugger in the Databricks notebook. The debugger is available only for Python.

The interactive debugger provides breakpoints, step-by-step execution, variable inspection, and more tools to help you develop code in notebooks more efficiently.

Requirements

Your notebook must be attached to a cluster that meets the following requirements:

  • Databricks Runtime version 13.3 LTS or above.

  • The access mode must be Single user (Assigned) or No isolation shared.

Enable or disable the debugger

To enable or disable the debugger, do the following:

  1. Click your username at the upper-right of the workspace and select Settings from the dropdown list.

  2. In the Settings sidebar, select Developer.

  3. In the Experimental features section, toggle Python Notebook Interactive Debugger.

Start the debugger

To start the debugger, follow these steps:

  1. Add one or more breakpoints by clicking in the gutter of a cell. To remove a breakpoint, click on it again.

    create and remove breakpoints video

  2. Do one of the following:

    • Click Run > Debug cell.

    • Use the keyboard shortcut Ctrl + Shift + D.

    • From the cell run menu, select Debug cell.

    debug cell item in cell run menu

A debug session starts automatically and runs the selected cell.

You can also start the debugger if a cell triggers an error. At the bottom of the cell output, click Debug button.

When a debug session is active, the debug toolbar Debug toolbar appears at the top of the cell.

Use the debugger

annotated debugger toolbar

In a debug session, you can do the following:

  • Set or remove breakpoints.

  • View the values of variables at a breakpoint.

  • Step through the code.

  • Step into or out of a function.

When the code reaches a breakpoint, it stops before the line is run, not after.

Use the buttons in the debugger toolbar to step through the code. As you step through the code, the current line is highlighted in the cell. You can view variable values in the variable explorer pane in the right sidebar.

When you step through a function, local function variables appear in the variable pane, marked [local].

Terminate a debugger session

To end the debugging session, click debugger stop button at the upper-left of the cell or click notebook stop button at the top of the notebook.

Limitations

  • The debugger works only with Python. It does not support Scala or R.

  • The debugger does not work on Shared access mode clusters.

  • The debugger does not support stepping into external files or modules.

  • When a debug session is active, you cannot run other commands in the notebook.