# Fix ipywidgets that render blank or fail in JupyterLab

Diagnose ipywidgets that show blank output or renderer errors in JupyterLab: classify kernel-side comm failures vs frontend/backend version mismatches from the visible symptom, verify the ipywidgets/jupyterlab_widgets version pairing, and resync with upgrade plus kernel restart and browser refresh.

Exact reference: {"kind":"skill_version","skill_id":"skl_k1sQms3TZ1sSaxWMCV6gNw","version_id":"skv_OQNjGqgf9jRCZtKVZU1IbQ"}

Applicability: [{"constraint":"8.x with jupyterlab_widgets 3.x on JupyterLab 3.x/4.x, or 7.x with jupyterlab-manager 2.x on JupyterLab 2.x","technology":"ipywidgets","version_scheme":"semver"},{"constraint":">=2.0","technology":"JupyterLab","version_scheme":"semver"}]

# Fix ipywidgets that render blank or fail in JupyterLab

Use this when a cell creating a widget (e.g. `widgets.IntSlider()`, `tqdm` notebook
bars, plotly figures rendered through ipywidgets) shows blank output, an error box,
or nothing at all. A widget has two halves — Python code in the kernel and a
JavaScript renderer in the browser — and the failure tells you which half is broken.
Classify first from the visible symptom, then fix that half.

## 1. Classify the failure from the visible symptom

**A. The output area shows an error box** mentioning the widget renderer, or the
browser console shows `Could not open comm` / `Control comm was closed too early`:
the kernel side failed. The widget's communication channel never opened or died —
usually the kernel was restarted after the widget was created, or the running
kernel doesn't have ipywidgets installed at all.

**B. The browser console shows `Cannot find model module @jupyter-widgets/controls`**
(or a similar module-not-found message): a frontend/backend version mismatch. The
Python ipywidgets in the kernel and the JupyterLab extension rendering it disagree.

**C. No error anywhere, just blank output:** usually B in disguise (mismatched
versions fail silently) or the rendering extension is missing entirely. Check
both halves anyway (steps 2 and 3).

## 2. Check the kernel half

From a cell in the running notebook:

```python
import ipywidgets
print(ipywidgets.__version__)
```

- `ImportError` / `ModuleNotFoundError`: ipywidgets is not installed in the
  kernel's environment. Install it into that environment (use the `%pip` magic
  inside a cell so it lands in the kernel's env, not the server's) and restart
  the kernel.
- `Control comm was closed too early` right after a kernel restart is expected:
  widget state lives in the kernel process, so outputs created before the restart
  cannot be revived. Re-run the cells that created the widgets; the old output
  areas will stay dead.

## 3. Check the browser half

```bash
jupyter labextension list
```

Look for a line like `@jupyter-widgets/jupyterlab-manager v5.x.x enabled OK`.
The version pairing that works (verified against the packages' own metadata):

- **ipywidgets 8.x** requires `jupyterlab_widgets~=3.0` and `widgetsnbextension~=4.0`
  (both pulled in automatically by `pip install ipywidgets`), and works with
  **JupyterLab 3.x and 4.x**. Per the jupyterlab-widgets README: "To enable
  ipywidgets support in JupyterLab 3.x or 4.x: `pip install jupyterlab_widgets`".
- **ipywidgets 7.x** pairs with **JupyterLab 2.x** via
  `jupyter labextension install @jupyter-widgets/jupyterlab-manager@2`.
  Prebuilt (pip-installable) widget extensions arrived with JupyterLab 3; older
  Labs need the manual `labextension install` with the matching major version.

If the manager line is missing, disabled, or its major version doesn't match the
Python ipywidgets major version, the browser half is broken.

## 4. Fix: resync the two halves, then restart and refresh

```bash
pip install --upgrade ipywidgets jupyterlab_widgets
# conda users: conda install -c conda-forge ipywidgets jupyterlab_widgets
```

Then do **both** of these — one without the other leaves the bug in place:

1. Restart the kernel and re-run the widget cells (new Python widget state).
2. Hard-refresh the browser page (or open a fresh tab). A newly installed
   frontend extension only takes effect in a freshly loaded page.

Classic Notebook 6.x (not JupyterLab / Notebook 7): stay on the ipywidgets 7
line and make sure the nbextension is enabled:

```bash
jupyter nbextension enable --py --sys-prefix widgetsnbextension
```

(This can be skipped for notebook version 5.3 and above, where it is enabled
automatically.)

## 5. Checklist for the broken widget

1. Reproduce and capture the exact symptom: error-box text or browser-console
   (F12) message.
2. Classify: comm error (kernel half) vs model-module error (version mismatch)
   vs blank (check both halves).
3. Kernel half: `import ipywidgets` works in the running kernel; re-run widget
   cells after every kernel restart.
4. Browser half: `@jupyter-widgets/jupyterlab-manager` present and enabled in
   `jupyter labextension list`, major version matching the Python ipywidgets.
5. Resync with the upgrade command, then restart the kernel AND refresh the page.


## Supporting basis and limitations

Built from the ipywidgets/jupyterlab-widgets installation documentation (version compatibility for JupyterLab 2.x/3.x/4.x), the PyPI dependency metadata for ipywidgets 7.x and 8.x (jupyterlab_widgets and widgetsnbextension requirements), and recurring Jupyter Discourse/GitHub threads on blank widgets and 'Cannot find model module' errors.

## Change and rationale

New skill: fix ipywidgets that render blank or fail in JupyterLab (kernel vs frontend classification, version pairing, resync).

Widgets going blank is one of the most-asked Jupyter questions and advice usually guesses at one half of the system. A widget has a Python half in the kernel and a JS half in the browser; this skill classifies which half broke from the observable symptom before prescribing the fix, and pins the real ipywidgets/jupyterlab_widgets version pairing instead of 'just reinstall everything'.