Install & Compatibility
Where this runs
tested against v0.11.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.910 runs
installs and imports cleanly · install 0.0s · import 1.009s · 93.1MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 5.9s · import 0.876s · 93MB
85MB installed
● package 85MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AnyWidget
✓ from anywidget import AnyWidget
Int
✓ import traitlets
class MyWidget(AnyWidget):
value = traitlets.Int(0).tag(sync=True)
Used for defining synchronized state between Python and JavaScript.
Unicode
✓ import traitlets
class MyWidget(AnyWidget):
text = traitlets.Unicode('Hello').tag(sync=True)
Used for defining synchronized string state.
This example defines a simple counter widget using `anywidget.AnyWidget`. It includes both Python (`traitlets.Int`) and JavaScript (`_esm`) components. The JavaScript code defines how the widget renders and interacts with the Python backend, including handling button clicks and updating a synchronized `count` traitlet. The `initialize` and `render` lifecycle hooks are the preferred way to define the frontend logic since v0.9.
import anywidget
import traitlets
from IPython.display import display
class CounterWidget(anywidget.AnyWidget):
_esm = """
export default {
initialize({ model }) {
// Optional: run once per widget instance
console.log('Widget initialized');
},
render({ model, el }) {
let getCount = () => model.get('count');
let button = document.createElement('button');
button.innerHTML = `count is ${getCount()}`;
button.addEventListener('click', () => {
model.set('count', getCount() + 1);
model.save_changes();
});
model.on('change:count', () => {
button.innerHTML = `count is ${getCount()}`;
});
el.appendChild(button);
return () => {
// Optional: cleanup on view removal
button.removeEventListener('click', () => {});
};
}
};
"""
_css = """ button { padding: 5px 10px; border-radius: 5px; background-color: #f0f0f0; } """
count = traitlets.Int(0).tag(sync=True)
widget = CounterWidget()
display(widget)
# You can also interact with the widget from Python
# widget.count = 5 # This will update the frontend
Debug
Known issues
breakingSince v0.9, the preferred way to define front-end widget code has shifted to using lifecycle hooks (`initialize`, `render`) exported as a default object from the `_esm` module, replacing the direct `export function render(view)` pattern.fixRefactor your `_esm` JavaScript to `export default { initialize({ model }), render({ model, el }) { ... } };`. The `render` function's argument `view` is now split into `{ model, el }`. affects: 0.9.0 and later
breakingIf you are using the Vite plugin for `anywidget`, the import path for it changed from `anywidget/vite` to `@anywidget/vite` to allow for independent versioning.fixUpdate your Vite configuration (e.g., `vite.config.mjs`) to `import anywidget from "@anywidget/vite";`.
affects: 0.7.0 and later
gotchaHot Module Replacement (HMR) for live development requires opting in by either setting the `ANYWIDGET_HMR` environment variable to `1` or, preferably, referencing frontend code via `pathlib.Path` for `_esm` and `_css` attributes.fixFor in-notebook prototyping, define `_esm` and `_css` as `pathlib.Path('index.js')` (or similar) to external files, and ensure the `ANYWIDGET_HMR` environment variable is set if you expect HMR without explicit file paths. affects: 0.2.0 and later
gotchaThe `__repr__` method for `AnyWidget` subclasses was overridden to provide a less verbose, `object.__repr__` like output, instead of the full serialization of all trait values inherited from `ipywidgets.Widget`.fixBe aware that inspecting `AnyWidget` instances directly might no longer show a full dump of all synchronized traits. For trait values, access them directly (e.g., `widget.count`).
affects: 0.9.19 and later
gotchaCustom messages sent from Python (`widget.send()`) will only be received by the frontend if the widget's view has already been rendered (i.e., the widget has been `display()`ed). Sending messages before the widget is displayed will result in them being lost.fixEnsure that the `AnyWidget` instance is displayed in the notebook or environment before sending any custom messages from the Python kernel.
affects: All versions
breakingFor `anywidget` framework bridges like `@anywidget/react` and `@anywidget/svelte`, there have been breaking changes to align with newer versions of their respective frameworks (React 18's `useSyncExternalStore` and Svelte 5's runes reactivity). This primarily affects users building widgets with these specific frontend frameworks.fixRefer to the `anywidget` release notes and the specific framework bridge documentation for migration guides if you are using `@anywidget/react` or `@anywidget/svelte`.
affects: Specific versions of `@anywidget/react` and `@anywidget/svelte` (e.g., `0.0.1` for `@anywidget/svelte`)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'anywidget'
The 'anywidget' package is not installed in the Python environment.
fixInstall the package using pip: 'pip install anywidget'.
ImportError: cannot import name 'AnyWidget' from 'anywidget'
The 'AnyWidget' class is not available in the 'anywidget' module, possibly due to an incorrect import statement or version mismatch.
fixEnsure you are using the correct import statement: 'from anywidget import AnyWidget'.
Failed to load model class 'AnyModel' from module 'anywidget'
Error: No version of module anywidget is registered
The JavaScript code for 'anywidget' is not available, possibly due to installation issues or the need to reload the Jupyter environment.
fixReload the browser tab running Jupyter or ensure 'anywidget' is installed before launching Jupyter.
Failed to load model class 'AnyModel' from module 'anywidget' Error: No version of module anywidget is registered.
This error typically occurs when anywidget's JavaScript frontend code is not properly loaded or activated in the Jupyter environment, often happening if anywidget was installed after Jupyter was launched or if there's an environment mismatch (e.g., in VS Code).
fixRestart your Jupyter server or reload the browser tab (not just the kernel). Ensure `anywidget` is installed in the correct environment where Jupyter is running, and if using `anywidget[dev]`, that your environment variables are correctly set for Hot Module Replacement (HMR).
Uncaught (in promise) Error: [anywidget] Failed to initialize model.
This specific error arises due to an incompatibility between `anywidget` and `websockets` versions 16.0 or higher, affecting the WebSocket communication layer `anywidget` relies on.
fixPin your `websockets` dependency to a version less than 16.0 in your `requirements.txt` or `conda` environment.yml, for example: `websockets<16.0`.
Upgrade
Version history
0.11.0latest on PyPI · released Apr 27, 2026
Audit
Dependencies
traitletsrequiredUsed for defining stateful properties synchronized between Python and JavaScript.
ipywidgetsoptionalWhile anywidget abstracts away much of ipywidgets, it's built on top of the Jupyter Widgets framework. The `[dev]` extra often pulls in ipywidgets for a complete Jupyter environment.