Debug notebooks

  • Article

Important

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 the debugger

Use the following steps to enable the debugger,:

  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 debugging

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. Start the debugging session by using one of the following options:

    • Click Run > Debug cell.
    • Use the keyboard shortcut Option + 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.

Debugging actions

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].

Debug console

When you start a debugging session, the debug console automatically appears in the bottom panel. This console allows you to execute Python code to inspect or manipulate variables when paused at a breakpoint. Code executed in the main notebook does not run during a debugging session. To run code in the console, press Enter. For multi-line expressions, use Shift + Enter to move to a new line.

debug_console

Note

  • The debug console is designed for quick evaluations and times out if the code execution exceeds 15 seconds.
  • The display command is not supported in the debug console. To view sample data from a DataFrame, use df.show() for PySpark DataFrames or df.head() for Pandas DataFrames.

Variable explorer

You can use the variable explorer panel the variable explorer icon on the right side to view the values of your variables. Clicking Inspect automatically executes code in the debug console to output the value of your variable.

example variable explorer panel

To filter the display, enter text into the search box. The list is automatically filtered as you type.

For Python on Databricks Runtime 12.2 LTS and above, the variables update as a cell runs. For Scala, R, and for Python on Databricks Runtime 11.3 LTS and below, variables update after a cell finishes running.

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. The debug session also automatically terminates after 30 minutes if the user does not use the debugging toolbar or debug console.

Limitations

See Known limitations Databricks notebooks for more information.