Install & Compatibility
Where this runs
tested against v8.1.9 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.714s · 85.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.2s · import 1.534s · 86MB
78MB installed
● package 78MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ipywidgets
✓ import ipywidgets as widgets
interact
✓ from ipywidgets import interact
display
✓ from IPython.display import display
Button
✓ from ipywidgets import Button
VBox
✓ from ipywidgets import VBox
Output
✓ from ipywidgets import Output
✗ from ipywidgets import out
Output is a class, 'out' is often used as an instance variable name.
This quickstart demonstrates creating an integer slider, observing its value changes, and displaying updates in a dedicated output area within a Jupyter notebook. It highlights the use of `ipywidgets.IntSlider` and `IPython.display.display` along with `ipywidgets.Output` for controlled output handling.
import ipywidgets as widgets
from IPython.display import display, HTML, clear_output
# Create a simple IntSlider widget
slider = widgets.IntSlider(
min=0,
max=100,
step=1,
description='Value:',
value=50
)
# Create an Output widget to capture print statements
output = widgets.Output()
# Define a function to be called when the slider's value changes
def on_value_change(change):
with output:
clear_output()
print(f"Slider value changed to: {change['new']}")
# Observe changes in the slider's value
slider.observe(on_value_change, names='value')
# Display the slider and the output area
display(HTML("<h3>Interactive Slider Example</h3>"))
display(slider, output)
Debug
Known issues
breakingThe `FileUpload` widget API changed significantly in version 8.x. The `.data` and `.metadata` traits were removed, and the `.value` trait was revamped to be a list of dictionaries, each containing file information (e.g., `content`, `name`, `type`, `size`, `last_modified`).fixRewrite usage of `FileUpload` to access file content and metadata through the new `.value` structure. For example, to get content bytes: `[f.content.tobytes() for f in uploader.value]`.
affects: 8.x and above
breakingThe `description_tooltip` attribute, used for tooltips on some widgets, was deprecated in favor of a universal `tooltip` attribute available on all widgets inheriting `DOMWidget` in version 8.x.fixReplace `description_tooltip` with `tooltip` in your widget instantiations and property assignments.
affects: 8.x and above
breakingThe `description` field of most widgets now sanitizes HTML content by default. If you rely on custom HTML in descriptions, it will be stripped or rendered as plain text.fixSet `description_allow_html=True` explicitly for the widget if you are in full control of the HTML content and require it to be rendered.
affects: 8.x and above
breakingThe method for setting titles on container widgets like `Accordion` or `Tab` changed. Direct calls to `container.set_title(index, title)` can cause `IndexError` if not handled correctly. It is now recommended to initialize with a `titles` tuple or assign to the `_titles` trait.fixWhen initializing `Accordion` or `Tab`, provide titles using the `titles` argument (e.g., `Accordion(children=[...], titles=('Title 1', 'Title 2'))`) or assign to the `_titles` trait after creation. affects: 8.x and above
gotchaDirect `print()` statements within functions linked to widgets (especially with `@interact` or `widget.observe()`) may not always display reliably or may appear in the console instead of the notebook output area in newer Jupyter environments.fixUse an `ipywidgets.Output` widget as a context manager to capture and display output reliably. Wrap `print()` calls within a `with output_widget:` block and use `clear_output()` for controlled updates.
affects: All versions, more prominent in JupyterLab 3+ / Notebook 7+
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'ipywidgets'
The `ipywidgets` Python package is not installed in the active Python environment or the Jupyter kernel where you are trying to use it.
fixInstall `ipywidgets` using pip or conda: `pip install ipywidgets` or `conda install ipywidgets`. Ensure you install it in the same environment that your Jupyter kernel is using.
Error displaying widget / widgets displaying as text (e.g., VBox(children=(Button(...))))
The Jupyter (Notebook/Lab) frontend extension for `ipywidgets` is either not installed, not enabled, or not correctly configured for the current environment, preventing the browser from rendering interactive controls. This can also be due to an outdated browser cache or an incompatible Jupyter version.
fixEnsure `ipywidgets` and the corresponding JupyterLab or classic Notebook extensions are installed and enabled. For JupyterLab 3.x+, use `pip install jupyterlab_widgets`. For older Jupyter Notebook, use `jupyter nbextension enable --py --sys-prefix widgetsnbextension`. After installation, restart Jupyter and perform a hard refresh of your browser page (Ctrl+Shift+R or Cmd+Shift+R).
AttributeError: module 'ipywidgets' has no attribute '...' (e.g., 'TagsInput', '_ipython_display_')
This error often indicates an API incompatibility, typically when upgrading `ipywidgets` (e.g., from version 7 to 8), where a feature, class, or attribute has been removed or renamed. It can also occur if a specific widget is not part of the core `ipywidgets` library.
fixConsult the `ipywidgets` documentation for the correct API for your installed version and update your code accordingly. If the attribute belongs to a custom widget, ensure that specific widget's package is installed and compatible with your `ipywidgets` version. Restarting the Python kernel may also help.
`ipywidgets.interact` shows the widget itself but does not apply the function
The callback function associated with `interact` is not being triggered, which can stem from conflicting Jupyter Notebook extensions, an unhealthy kernel state, or JavaScript execution issues within the browser environment.
fixTry disabling any potentially conflicting Jupyter Notebook extensions (e.g., 'Limit Output'). Verify that the Jupyter kernel is running and healthy. Restart the kernel and rerun all cells in the notebook. A hard refresh of your browser or trying a different browser may also resolve the issue.
Upgrade
Version history
8.1.9latest on PyPI · released Aug 18, 2026
Audit
Dependencies
widgetsnbextensionoptionalAutomatically installed for classic Jupyter Notebook to display widgets. Explicit installation may be needed if Jupyter components are in separate environments.
jupyterlab_widgetsoptionalAutomatically installed for JupyterLab 3.x+ to display widgets. Explicit installation may be needed if Jupyter components are in separate environments.
notebookoptionalAs of ipywidgets 8, the 'notebook' package is no longer a direct dependency and must be installed explicitly if required for your environment.