Run the notebook interactively

The Jupyter notebook page in these docs is a static preview (markdown and code only). To see the live ipywidgets display and run touch examples, use Jupyter on your machine.

Quick start

From a clone of PyDevices/pydisplay:

cd pydisplay
python3 -m venv .venv
.venv/bin/pip install pillow ipywidgets ipyevents jupyterlab
.venv/bin/jupyter lab --no-browser

Or use the helper script from the repo root (starts JupyterLab and opens a demo):

./tools/jupyter.sh calculator
./tools/jupyter.sh calculator --cursor

Generated demo notebooks are written to src/run-{demo}.ipynb (gitignored). The hub notebook is src/jupyter_notebook.ipynb.

Open the URL printed in the terminal (for example http://127.0.0.1:8888/lab/tree/run-calculator.ipynb) in a browser, or use --cursor to open in the editor instead.

Select the .venv kernel (Kernel → Change Kernel), then run cells top to bottom.

Requirements

Package	Purpose
Pillow	Image buffers for JNDisplay
ipywidgets	Interactive display widget
ipyevents	Mouse / keyboard on the widget
JupyterLab or Jupyter Notebook	Notebook UI in the browser

No LVGL build is required for the pydisplay walkthrough in the notebook.

src/lib/board_config.py detects Jupyter (get_ipython()) and selects JNDisplay with TIMER_ASYNC = True. The notebook must run with working directory under src/ so import lib.path finds lib/, examples/, and add_ons/ — opening src/jupyter_notebook.ipynb from the repo in JupyterLab does that automatically.

Touch input

After a cell runs, an Image widget appears below the output. Click that widget for touch — not the cell chrome and not the static ReadTheDocs page.

JNDevices maps mouse events on the widget to the same event API as on hardware. See Jupyter platform notes for limitations (touch only in the notebook; no encoder emulation).

VS Code / Cursor

You can run the same notebook in the editor instead of a browser tab:

1. Open src/jupyter_notebook.ipynb.
2. Choose the .venv interpreter as the notebook kernel.
3. If the widget area is blank, set jupyter.widgetScriptSources to load widget JavaScript (this repo’s .vscode/settings.json uses jsdelivr.com and unpkg.com).
4. Reload the window, restart the kernel, and re-run.

Stopping background examples

Cells that import async examples schedule work with multimer.run() and return immediately. The square Stop button often does not cancel them. Use Kernel → Restart to stop.

One-shot example cells block until the drawing finishes; Stop works there.

Download the notebook

On the static notebook preview page, use the download button at the top, or open src/jupyter_notebook.ipynb on GitHub.

More detail

• Jupyter platform — async execution model, board config, when to use Jupyter vs desktop or PyScript
• Building docs — why the docs build does not execute the notebook