ipywidgets

Preview

This feature is in Public Preview.

ipywidgets are visual elements that allow users to specify parameter values in notebook cells. You can use ipywidgets to make your Databricks Python notebooks interactive.

The ipywidgets package includes over 30 different controls, including form controls such as sliders, text boxes, and checkboxes, as well as layout controls such as tabs, accordions, and grids. Using these elements, you can build graphical user interfaces to interface with your notebook code.

Note

For information about Databricks widgets, see Databricks widgets. For guidelines on when to use Databricks widgets or ipywidgets, see Best practices for using ipywidgets and Databricks widgets.

Requirements

ipywidgets are available in Databricks Runtime 11.1 and above.

Note

By default, ipywidgets occupies port 6062. With Databricks Runtime 11.2 and above, if you run into conflicts with third-party integrations such as Datadog, you can change the port using the following Spark config:

spark.databricks.driver.ipykernel.commChannelPort <port-number>

For example:

spark.databricks.driver.ipykernel.commChannelPort 1234

The Spark config must be set when the cluster is created.

Usage

The following code creates a histogram with a slider that can take on values between 3 and 10. The value of the widget determines the number of bins in the histogram. As you move the slider, the histogram updates immediately. See the ipywidgets example notebook to try this out.

import ipywidgets as widgets
from ipywidgets import interact

# Load a dataset
sparkDF = spark.read.csv("/databricks-datasets/bikeSharing/data-001/day.csv", header="true", inferSchema="true")

# In this code, `(bins=(3, 10)` defines an integer slider widget that allows values between 3 and 10.
@interact(bins=(3, 10))
def plot_histogram(bins):
  pdf = sparkDF.toPandas()
  pdf.hist(column='temp', bins=bins)

The following code creates an integer slider that can take on values between 0 and 10. The default value is 5. To access the value of the slider in your code, use int_slider.value.

import ipywidgets as widgets

int_slider = widgets.IntSlider(max=10, value=5)
int_slider

Example notebooks

ipywidgets example notebook

Open notebook in new tab

Advanced example: maps with ipywidgets

Open notebook in new tab

Best practices for using ipywidgets and Databricks widgets

To add interactive controls to Python notebooks, Databricks recommends using ipywidgets. For notebooks in other languages, use Databricks widgets.

You can use Databricks widgets to pass parameters between notebooks and to pass parameters to jobs; ipywidgets do not support these scenarios.

Which third-party Jupyter widgets are supported in Databricks?

Databricks provides best-effort support for third-party widgets, such as ipyleaflet, bqplot, and VegaFusion. However, some third-party widgets are not supported. For a list of the widgets that have been tested in Databricks notebooks, contact your Databricks representative.

Limitations

  • A notebook using ipywidgets must be attached to a running cluster.

  • Widget states are not preserved across notebook sessions. You must re-run widget cells to render them each time you attach the notebook to a cluster.

  • The following ipywidgets are not supported: Password, File Upload, Controller.

  • HTMLMath and Label widgets with LaTeX expressions do not render correctly. (For example, widgets.Label(value=r'$$\frac{x+1}{x-1}$$') does not render correctly.)

  • Widgets might not render properly if the notebook is in dark mode, especially colored widgets.

  • Widget outputs cannot be used in notebook dashboard views.

  • The maximum message payload size for an ipywidget is 5 MB. Widgets that use images or large text data may not be properly rendered.