Install & Compatibility
Where this runs
tested against v1.1.0 · 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.920 runs
installs and imports cleanly · install 0.0s · import 1.663s · 80.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.7s · import 1.486s · 81MB
72MB installed
● package 72MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ui_events
✓ from jupyter_ui_poll import ui_events
Used for synchronous-like polling with a 'with' statement.
with_ui_events
✓ from jupyter_ui_poll import with_ui_events
Used for asynchronous iteration over events with an 'async for' statement (available since v0.2.0).
run_ui_poll_loop
✓ from jupyter_ui_poll import run_ui_poll_loop
Lower-level function for custom poll loops, often used in async contexts (available since v0.2.0).
This quickstart demonstrates how to use `jupyter-ui-poll` to block cell execution until a user interacts with an `ipywidget`. A button is displayed, and the `ui_events` context manager is used to create a polling loop. The `poll(10)` call allows Jupyter to process UI events (like button clicks) while the `while` loop is active, ensuring the notebook doesn't hang. Once the button is clicked, the `ui_done` flag is set, and the cell execution proceeds.
import time
from ipywidgets import Button, display
from jupyter_ui_poll import ui_events
# Global flag to control the loop
ui_done = False
def on_click(btn):
global ui_done
ui_done = True
btn.description = 'Done!'
# Create a button
button = Button(description='Click Me to Continue')
button.on_click(on_click)
display(button)
print('Waiting for button click...')
# Wait for user to press the button, processing UI events
with ui_events() as poll:
while not ui_done:
poll(10) # Process up to 10 UI events per call
print('.', end='', flush=True)
time.sleep(0.1) # Prevent busy-waiting
print('\nButton clicked! Execution continues.')
Debug
Known issues
breakingVersion `0.2.0a0` introduced breaking changes by making the library async-only. Synchronous usage patterns for `with_ui_events` and `run_ui_poll_loop` were removed, requiring `async with` and `async for` instead. While `v0.2.0` later re-introduced synchronous support for `ui_events`, if you are on an `ipykernel` >= 6, the async patterns might be required for certain operations.fixMigrate blocking code to `async with ui_events() as poll: await poll()` or `async for x in with_ui_events(iterable):`. For `ipykernel<6`, the synchronous `with ui_events() as poll: poll()` is generally safe. For `ipykernel>=6`, be mindful of async requirements, especially when integrating with other async code.
affects: 0.2.0a0 - <0.2.0
breakingVersion `1.1.0` includes crucial fixes for `ipykernel` series 7+. Newer `ipykernel` versions introduce internal locks that stop message processing during cell execution. `jupyter-ui-poll` v1.1.0 dynamically patches the running kernel instance to bypass this lock and allow UI event processing. Older versions of `jupyter-ui-poll` will likely cease to function correctly with `ipykernel` 7+.fixUpgrade to `jupyter-ui-poll==1.1.0` or newer to ensure compatibility with `ipykernel` 7 series. `pip install --upgrade jupyter-ui-poll`.
affects: <1.1.0 with ipykernel 7+
gotcha`jupyter-ui-poll` has historically had to adapt to significant changes in `ipykernel`'s internal architecture across major versions (e.g., v5, v6, v7). This means that a `jupyter-ui-poll` version compatible with `ipykernel` v5 might not work with v6 or v7, and vice-versa. Always check the release notes for specific `ipykernel` compatibility details.fixAlways install the latest `jupyter-ui-poll` version. If encountering issues, ensure your `ipykernel` version is compatible with your `jupyter-ui-poll` version. Consider using a pinned version of `ipykernel` if stability is critical.
affects: All versions
Errors
Common errors & fixes
The polling mechanism no longer works under the latest release of ipykernel from pip. ... The most immediate problem is that do_one_iteration is now an async method.
Incompatibility between `jupyter-ui-poll` and a newer `ipykernel` version, specifically when `ipykernel`'s internal event loop methods become asynchronous.
fixUpgrade `jupyter-ui-poll` to the latest version. For `ipykernel` 6+, you may need to adopt `async` patterns in your `jupyter-ui-poll` usage (e.g., `async with ui_events() as poll: await poll()`) or ensure your `jupyter-ui-poll` version explicitly supports your `ipykernel` version.
Jupyter kernel died / Jupyter Notebook connection error
While not directly a `jupyter-ui-poll` error, an incompatible `jupyter-ui-poll` or `ipykernel` setup can destabilize the kernel. If `jupyter-ui-poll` fails to correctly hook into the kernel's event handling, it can lead to dead kernels or connection issues. This can also be caused by general `ipykernel` installation issues, or conflicting `pyzmq` versions.
fixFirst, ensure `jupyter-ui-poll` is the latest version. If the issue persists, try reinstalling `ipykernel` and `jupyter-ui-poll` in a fresh environment. Check for `pyzmq` compatibility issues by uninstalling and reinstalling it (e.g., `pip uninstall pyzmq; pip install pyzmq==19.0.2` if an older version is needed, or the latest otherwise).
Callbacks you have registered with the widget library won't get a chance to run and so state of app.have_all_the_data() won't ever change.
This is the fundamental problem `jupyter-ui-poll` solves. Without `jupyter-ui-poll`, Jupyter's kernel is busy executing the current cell and does not process UI events or callbacks from widgets, leading to unresponsive UIs and blocking logic.
fixWrap your polling logic within `with ui_events() as poll:` and call `poll()` periodically inside your loop to explicitly process UI events. Alternatively, use `async for` with `with_ui_events()` for asynchronous iterables.
Upgrade
Version history
1.1.0latest on PyPI · released Oct 31, 2025
Audit
Dependencies
ipykernelrequiredCore dependency for Jupyter environment, critical for operation. Version compatibility is a frequent concern across jupyter-ui-poll releases.
ipywidgetsoptionalCommonly used for building the interactive UI that jupyter-ui-poll manages.